newch 0.2.0__tar.gz

newch-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

newch-0.2.0/MANIFEST.in

@@ -0,0 +1,6 @@
+graft engine
+include tools/build.py
+include README.md LICENSE NOTICE
+recursive-include docs *.md
+prune build
+global-exclude *.pyc *.dll *.so *.dylib *.exe *.pdb

newch-0.2.0/NOTICE

@@ -0,0 +1,8 @@
+newch
+Copyright 2026 The newch authors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Third-party algorithms:
+- xoshiro256** and splitmix64 random number generators, by David Blackman
+  and Sebastiano Vigna (public domain, https://prng.di.unimi.it/).

newch-0.2.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: newch
+Version: 0.2.0
+Summary: A small machine-learning library for low-spec machines: PyTorch-style autograd, Keras-style fit, portable C engine
+Author: The newch authors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/dandmadp/newch
+Project-URL: Source, https://github.com/dandmadp/newch
+Project-URL: Issues, https://github.com/dandmadp/newch/issues
+Project-URL: Documentation, https://github.com/dandmadp/newch/blob/main/docs/PROGRESS.md
+Keywords: machine learning,deep learning,autograd,neural network,embedded,low-spec
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: numpy
+Requires-Dist: numpy; extra == "numpy"
+Dynamic: license-file
+
+# newch
+
+저사양 기기에서도 **학습**까지 할 수 있는 작은 머신러닝 라이브러리입니다. 엔진은 C11이고, Python에서는
+PyTorch 스타일 텐서와 autograd, Keras 스타일 `compile`/`fit`을 씁니다. Python 의존성은 없습니다
+(numpy가 있으면 사용합니다). 싱글보드 컴퓨터는 호환 대상 중 하나입니다.
+
+- 네이티브 라이브러리 약 200KB (Windows), aarch64 리눅스용 약 90KB
+- MNIST CNN: 1 에포크 18초, 테스트 정확도 98.1% (x86 PC, 디스크에서 스트리밍)
+- 행렬곱: 멀티스레드 + AVX2로 numpy(BLAS)의 0.9~1.5배 시간
+
+## 설치
+
+```
+pip install newch            # Windows x86-64는 바로 설치, 그 밖의 플랫폼은 설치 중 엔진을 컴파일합니다
+pip install "newch[numpy]"   # numpy 연동까지
+```
+
+소스에서 설치할 때도 시스템 C 컴파일러는 필요 없습니다 (pip 패키지 `ziglang`을 씁니다).
+저장소에서는 `pip install .`, 개발할 때는 `pip install ziglang` 후 `python tools/build.py`를 실행합니다.
+라이선스는 Apache-2.0입니다 ([LICENSE](https://github.com/dandmadp/newch/blob/main/LICENSE), [NOTICE](https://github.com/dandmadp/newch/blob/main/NOTICE)).
+
+## Python 사용 예
+
+```python
+import newch as nc
+from newch import net
+
+# Keras 스타일
+model = nc.Sequential([
+    net.Conv2d(1, 16, 3, padding=1), net.BatchNorm2d(16), net.ReLU(), net.MaxPool2d(2),
+    net.Flatten(), net.Dropout(0.25), net.Linear(16 * 14 * 14, 10),
+])
+model.compile(optimizer="adam", loss="cross_entropy", metrics=["accuracy"])
+model.summary()
+history = model.fit(x, y, epochs=5, validation_split=0.1,
+                    callbacks=[nc.callbacks.EarlyStopping(patience=2)])
+loss, acc = model.evaluate(x_test, y_test)
+model.save_weights("model.ncw")          # 다른 기기에서 model.load_weights(...)
+
+# PyTorch 스타일
+opt = nc.optim.Adam(model.parameters(), lr=1e-3)
+for xb, yb in loader:
+    loss = nc.cross_entropy(model(xb), yb)
+    opt.zero_grad(); loss.backward(); opt.step()
+    nc.step_end()                         # 이 스텝의 임시 텐서를 한 번에 해제
+```
+
+**RAM보다 큰 데이터셋:** 샘플을 디스크 파일에 저장하고 `FileArray`로 열면 배치 단위로만 읽습니다.
+
+```python
+from newch.data import DataLoader, FileArray, TensorDataset
+
+x = FileArray.create("x.bin", rows, row_shape=(1, 28, 28))   # 한 행씩 기록
+y = FileArray.create("y.bin", labels, row_shape=(), dtype=nc.int32)
+model.fit(DataLoader(TensorDataset(x, y), batch_size=64, shuffle=True), epochs=3)
+```
+
+**PyTorch 가중치 가져오기:** 레이어 이름과 레이아웃이 같으므로 numpy로 바꿔서 넣으면 됩니다.
+
+```python
+model.load_state_dict({k: v.numpy() for k, v in torch_model.state_dict().items()})
+```
+
+**int8 양자화 (추론):** `nc.quantize_(model)`은 모든 `Linear`를 int8 가중치로 바꿉니다 (가중치 메모리 1/4).
+
+**스레드:** 기본값은 모든 코어입니다. `nc.set_default_context(nc.Context(threads=2))`로 바꿀 수 있습니다.
+
+전체 예제는 [examples/mnist_cnn.py](https://github.com/dandmadp/newch/blob/main/examples/mnist_cnn.py)에 있습니다 (다운로드 → 디스크 변환 → 스트리밍 학습 → 저장 → 양자화).
+
+PyTorch나 Keras와 이름이 같은 API는 동작도 같고, 의미가 다른 경우에는 다른 이름을 씁니다
+(목록은 [docs/PROGRESS.md](https://github.com/dandmadp/newch/blob/main/docs/PROGRESS.md)의 "이름 규칙").
+
+## C 사용 예
+
+```c
+nc_ctx *ctx = nc_init(&(nc_config){.threads = 0});            /* 0 = 모든 코어 */
+nc_module *layers[] = {nc_linear(ctx, 2, 64, 1), nc_act(ctx, NC_ACT_RELU), nc_linear(ctx, 64, 3, 1)};
+nc_module *model = nc_sequential(ctx, 3, layers);
+nc_tensor *params[16];
+int np = nc_parameters(model, params, 16);
+nc_optim *opt = nc_adam(ctx, params, np, (nc_optim_opts){.lr = 1e-3f});
+
+for (int step = 0; step < steps; step++) {
+    nc_tensor *x = nc_from_data(ctx, NC_F32, batch_x, 2, (int64_t[]){B, 2});
+    nc_tensor *y = nc_from_data(ctx, NC_I32, batch_y, 1, (int64_t[]){B});
+    nc_tensor *loss = nc_cross_entropy(nc_forward(model, x), y);
+    nc_optim_zero_grad(opt);
+    nc_backward(loss);
+    nc_optim_step(opt);
+    if (!nc_ok(ctx)) { puts(nc_error(ctx)); break; }   /* 에러는 한 번에 확인 */
+    nc_step_end(ctx);                                   /* 임시 텐서 전부 해제, O(1) */
+}
+const char *names[] = {"w", "b"};
+nc_save(ctx, "model.ncw", 2, names, params);
+nc_free_ctx(ctx);
+```
+
+## 지원 플랫폼
+
+| 타깃 (`tools/build.py --target`) | 대표 기기 | 커널 |
+|---|---|---|
+| `host` | 개발 PC (Windows / Linux / macOS) | x86: AVX2+FMA (런타임 감지), ARM: NEON |
+| `aarch64`, `aarch64-static` | Pi 3/4/5, Orange Pi 5, RK35xx, Apple Silicon | NEON |
+| `armv7`, `armv7-static` | Pi 2/3 (32비트 OS), 구형 Allwinner | NEON (런타임 확인) |
+| `riscv64`, `riscv64-static` | VisionFive 2, Milk-V, BPI-F3 | 레퍼런스 (RVV 예정) |
+
+`*-static`은 musl 정적 링크 바이너리라서 어떤 리눅스 기기에든 복사해서 바로 실행할 수 있습니다.
+기기에서 직접 빌드할 때는 `cmake -B build && cmake --build build -j && ctest --test-dir build`.
+
+## 핵심 설계
+
+- **메모리:** 파라미터 등 영구 텐서와 스텝 아레나(활성값, 중간 그래디언트)를 나눕니다. `step_end()`가 아레나를 O(1)로
+  되돌리고, `trim()`이 남는 메모리를 OS에 반환합니다. Python에서는 영구 텐서를 마지막 참조가 사라질 때 자동으로 해제합니다
+- **에러:** 연산은 abort하지 않습니다. 첫 에러를 기록하고 NULL을 전파하며, Python에서는 `NcError`가 됩니다
+- **연산은 데이터로 기술:** 모든 연산이 `nc_op_def`(infer/view/forward/backward)로 등록되고 `nc__apply()`를 거칩니다
+- **커널 디스패치:** 레퍼런스 테이블에서 시작해 CPU가 지원하는 계층(NEON, AVX2)이 항목별로 덮어씁니다.
+  `test_kernel_parity`가 모든 계층을 레퍼런스와 비교합니다
+- **스레드:** 큰 GEMM만 행 또는 열 단위로 나눠 병렬 실행합니다. 출력 원소 하나는 스레드 하나가 계산하므로 결과가 스레드 수와
+  무관하게 비트 단위로 같습니다
+
+## 디렉터리
+
+```
+engine/include/nc.h        공개 C API (NC_API로 표시된 함수만 공유 라이브러리에서 노출)
+engine/src/core/           컨텍스트, 메모리, 텐서, 레지스트리, 파일 입출력
+engine/src/autograd/       nc__apply, 테이프, backward, gradcheck
+engine/src/ops/            elementwise, linalg, reduce, shape, nn, conv, quant
+engine/src/kernels/        디스패치, ref/, neon/, x86/(AVX2)
+engine/src/runtime/        CPU 감지, 스레드 풀
+engine/tests/              C 테스트
+newch/                     Python 패키지 (tensor, net, optim, data, training, callbacks)
+tests/                     Python 테스트
+examples/                  train_spiral.c, mnist_cnn.py
+docs/                      PROGRESS.md (작업 요약), FORMAT.md (가중치 파일 포맷)
+tools/build.py             zig cc 기반 멀티 타깃 빌드
+.github/workflows/ci.yml   CI (Windows/Linux/macOS, QEMU ARM·RISC-V, 휠)
+```

newch-0.2.0/README.md

@@ -0,0 +1,137 @@
+# newch
+
+저사양 기기에서도 **학습**까지 할 수 있는 작은 머신러닝 라이브러리입니다. 엔진은 C11이고, Python에서는
+PyTorch 스타일 텐서와 autograd, Keras 스타일 `compile`/`fit`을 씁니다. Python 의존성은 없습니다
+(numpy가 있으면 사용합니다). 싱글보드 컴퓨터는 호환 대상 중 하나입니다.
+
+- 네이티브 라이브러리 약 200KB (Windows), aarch64 리눅스용 약 90KB
+- MNIST CNN: 1 에포크 18초, 테스트 정확도 98.1% (x86 PC, 디스크에서 스트리밍)
+- 행렬곱: 멀티스레드 + AVX2로 numpy(BLAS)의 0.9~1.5배 시간
+
+## 설치
+
+```
+pip install newch            # Windows x86-64는 바로 설치, 그 밖의 플랫폼은 설치 중 엔진을 컴파일합니다
+pip install "newch[numpy]"   # numpy 연동까지
+```
+
+소스에서 설치할 때도 시스템 C 컴파일러는 필요 없습니다 (pip 패키지 `ziglang`을 씁니다).
+저장소에서는 `pip install .`, 개발할 때는 `pip install ziglang` 후 `python tools/build.py`를 실행합니다.
+라이선스는 Apache-2.0입니다 ([LICENSE](https://github.com/dandmadp/newch/blob/main/LICENSE), [NOTICE](https://github.com/dandmadp/newch/blob/main/NOTICE)).
+
+## Python 사용 예
+
+```python
+import newch as nc
+from newch import net
+
+# Keras 스타일
+model = nc.Sequential([
+    net.Conv2d(1, 16, 3, padding=1), net.BatchNorm2d(16), net.ReLU(), net.MaxPool2d(2),
+    net.Flatten(), net.Dropout(0.25), net.Linear(16 * 14 * 14, 10),
+])
+model.compile(optimizer="adam", loss="cross_entropy", metrics=["accuracy"])
+model.summary()
+history = model.fit(x, y, epochs=5, validation_split=0.1,
+                    callbacks=[nc.callbacks.EarlyStopping(patience=2)])
+loss, acc = model.evaluate(x_test, y_test)
+model.save_weights("model.ncw")          # 다른 기기에서 model.load_weights(...)
+
+# PyTorch 스타일
+opt = nc.optim.Adam(model.parameters(), lr=1e-3)
+for xb, yb in loader:
+    loss = nc.cross_entropy(model(xb), yb)
+    opt.zero_grad(); loss.backward(); opt.step()
+    nc.step_end()                         # 이 스텝의 임시 텐서를 한 번에 해제
+```
+
+**RAM보다 큰 데이터셋:** 샘플을 디스크 파일에 저장하고 `FileArray`로 열면 배치 단위로만 읽습니다.
+
+```python
+from newch.data import DataLoader, FileArray, TensorDataset
+
+x = FileArray.create("x.bin", rows, row_shape=(1, 28, 28))   # 한 행씩 기록
+y = FileArray.create("y.bin", labels, row_shape=(), dtype=nc.int32)
+model.fit(DataLoader(TensorDataset(x, y), batch_size=64, shuffle=True), epochs=3)
+```
+
+**PyTorch 가중치 가져오기:** 레이어 이름과 레이아웃이 같으므로 numpy로 바꿔서 넣으면 됩니다.
+
+```python
+model.load_state_dict({k: v.numpy() for k, v in torch_model.state_dict().items()})
+```
+
+**int8 양자화 (추론):** `nc.quantize_(model)`은 모든 `Linear`를 int8 가중치로 바꿉니다 (가중치 메모리 1/4).
+
+**스레드:** 기본값은 모든 코어입니다. `nc.set_default_context(nc.Context(threads=2))`로 바꿀 수 있습니다.
+
+전체 예제는 [examples/mnist_cnn.py](https://github.com/dandmadp/newch/blob/main/examples/mnist_cnn.py)에 있습니다 (다운로드 → 디스크 변환 → 스트리밍 학습 → 저장 → 양자화).
+
+PyTorch나 Keras와 이름이 같은 API는 동작도 같고, 의미가 다른 경우에는 다른 이름을 씁니다
+(목록은 [docs/PROGRESS.md](https://github.com/dandmadp/newch/blob/main/docs/PROGRESS.md)의 "이름 규칙").
+
+## C 사용 예
+
+```c
+nc_ctx *ctx = nc_init(&(nc_config){.threads = 0});            /* 0 = 모든 코어 */
+nc_module *layers[] = {nc_linear(ctx, 2, 64, 1), nc_act(ctx, NC_ACT_RELU), nc_linear(ctx, 64, 3, 1)};
+nc_module *model = nc_sequential(ctx, 3, layers);
+nc_tensor *params[16];
+int np = nc_parameters(model, params, 16);
+nc_optim *opt = nc_adam(ctx, params, np, (nc_optim_opts){.lr = 1e-3f});
+
+for (int step = 0; step < steps; step++) {
+    nc_tensor *x = nc_from_data(ctx, NC_F32, batch_x, 2, (int64_t[]){B, 2});
+    nc_tensor *y = nc_from_data(ctx, NC_I32, batch_y, 1, (int64_t[]){B});
+    nc_tensor *loss = nc_cross_entropy(nc_forward(model, x), y);
+    nc_optim_zero_grad(opt);
+    nc_backward(loss);
+    nc_optim_step(opt);
+    if (!nc_ok(ctx)) { puts(nc_error(ctx)); break; }   /* 에러는 한 번에 확인 */
+    nc_step_end(ctx);                                   /* 임시 텐서 전부 해제, O(1) */
+}
+const char *names[] = {"w", "b"};
+nc_save(ctx, "model.ncw", 2, names, params);
+nc_free_ctx(ctx);
+```
+
+## 지원 플랫폼
+
+| 타깃 (`tools/build.py --target`) | 대표 기기 | 커널 |
+|---|---|---|
+| `host` | 개발 PC (Windows / Linux / macOS) | x86: AVX2+FMA (런타임 감지), ARM: NEON |
+| `aarch64`, `aarch64-static` | Pi 3/4/5, Orange Pi 5, RK35xx, Apple Silicon | NEON |
+| `armv7`, `armv7-static` | Pi 2/3 (32비트 OS), 구형 Allwinner | NEON (런타임 확인) |
+| `riscv64`, `riscv64-static` | VisionFive 2, Milk-V, BPI-F3 | 레퍼런스 (RVV 예정) |
+
+`*-static`은 musl 정적 링크 바이너리라서 어떤 리눅스 기기에든 복사해서 바로 실행할 수 있습니다.
+기기에서 직접 빌드할 때는 `cmake -B build && cmake --build build -j && ctest --test-dir build`.
+
+## 핵심 설계
+
+- **메모리:** 파라미터 등 영구 텐서와 스텝 아레나(활성값, 중간 그래디언트)를 나눕니다. `step_end()`가 아레나를 O(1)로
+  되돌리고, `trim()`이 남는 메모리를 OS에 반환합니다. Python에서는 영구 텐서를 마지막 참조가 사라질 때 자동으로 해제합니다
+- **에러:** 연산은 abort하지 않습니다. 첫 에러를 기록하고 NULL을 전파하며, Python에서는 `NcError`가 됩니다
+- **연산은 데이터로 기술:** 모든 연산이 `nc_op_def`(infer/view/forward/backward)로 등록되고 `nc__apply()`를 거칩니다
+- **커널 디스패치:** 레퍼런스 테이블에서 시작해 CPU가 지원하는 계층(NEON, AVX2)이 항목별로 덮어씁니다.
+  `test_kernel_parity`가 모든 계층을 레퍼런스와 비교합니다
+- **스레드:** 큰 GEMM만 행 또는 열 단위로 나눠 병렬 실행합니다. 출력 원소 하나는 스레드 하나가 계산하므로 결과가 스레드 수와
+  무관하게 비트 단위로 같습니다
+
+## 디렉터리
+
+```
+engine/include/nc.h        공개 C API (NC_API로 표시된 함수만 공유 라이브러리에서 노출)
+engine/src/core/           컨텍스트, 메모리, 텐서, 레지스트리, 파일 입출력
+engine/src/autograd/       nc__apply, 테이프, backward, gradcheck
+engine/src/ops/            elementwise, linalg, reduce, shape, nn, conv, quant
+engine/src/kernels/        디스패치, ref/, neon/, x86/(AVX2)
+engine/src/runtime/        CPU 감지, 스레드 풀
+engine/tests/              C 테스트
+newch/                     Python 패키지 (tensor, net, optim, data, training, callbacks)
+tests/                     Python 테스트
+examples/                  train_spiral.c, mnist_cnn.py
+docs/                      PROGRESS.md (작업 요약), FORMAT.md (가중치 파일 포맷)
+tools/build.py             zig cc 기반 멀티 타깃 빌드
+.github/workflows/ci.yml   CI (Windows/Linux/macOS, QEMU ARM·RISC-V, 휠)
+```

newch-0.2.0/docs/FORMAT.md

@@ -0,0 +1,26 @@
+# NCW1 텐서 파일 포맷
+
+`nc_save` / `nc_load` (C), `save_tensors` / `load_tensors`, `save_weights` / `load_weights` (Python)가 쓰는 포맷입니다.
+모든 정수는 리틀 엔디언입니다.
+
+```
+offset  크기        내용
+0       4           매직 "NCW1"
+4       u32         버전 (1)
+8       u32         엔트리 수 n
+12      ...         엔트리 n개
+
+엔트리:
+  u32               이름 길이 L (바이트, 최대 4096)
+  L                 이름 (UTF-8, 널 문자 없음)
+  u32               dtype: 0 = f32, 1 = i32, 3 = i8
+  u32               차원 수 d (최대 6)
+  i64 × d           shape
+  u64               데이터 바이트 수 B (= 원소 수 × dtype 크기)
+  B                 데이터 (row-major, 연속)
+```
+
+- 이름은 `state_dict()` 키입니다 (`0.weight`, `1.running_mean` 등, PyTorch와 같은 규칙)
+- 읽는 쪽은 요청하지 않은 엔트리를 건너뛰므로, 파일에 추가 텐서가 있어도 됩니다
+- `nc_load`는 이름이 없거나 dtype/shape가 다르면 에러를 냅니다. Python `load_weights`는 `load_state_dict(strict=True)`와 같은 규칙입니다
+- 양자화된 `Linear`는 `weight`(i8 `[out, in]`), `scale`(f32 `[out]`), `bias`(f32 `[out]`)로 저장됩니다