diff --git a/.github/workflows/python-reference.yml b/.github/workflows/python-reference.yml new file mode 100644 index 0000000..eae7b42 --- /dev/null +++ b/.github/workflows/python-reference.yml @@ -0,0 +1,28 @@ +name: Python reference + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: + contents: read + +jobs: + reference: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest, windows-latest] + steps: + - uses: actions/checkout@v7 + with: + submodules: recursive + - uses: actions/setup-python@v7 + with: + python-version: '3.12' + - name: Check gradients, convergence, and paths + run: python -m unittest discover -s python/tests -v + - name: Run the seeded example + run: python python/examples/xor_demo.py --seed 0 diff --git a/.gitmodules b/.gitmodules index 1806622..3d896b9 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,9 +1,9 @@ [submodule "cpp"] path = cpp - url = git@github.com:lonlydwolf/Cpp-Neural-Network.git + url = https://github.com/lonlydwolf/Cpp-Neural-Network.git [submodule "csharp"] path = csharp - url = git@github.com:lonlydwolf/C-Sharp-Neural-Network.git + url = https://github.com/lonlydwolf/C-Sharp-Neural-Network.git [submodule "python"] path = python - url = git@github.com:lonlydwolf/Python-Neural-Network.git + url = https://github.com/lonlydwolf/Python-Neural-Network.git diff --git a/README.md b/README.md index bfb3b7f..db0ba3d 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,57 @@ # XOR First-Principles Network -A fully connected neural network compiled without third-party frameworks to cement absolute mathematical understanding of algorithmic updates. Hand-coded across C++, C#, and Python yielding identical results. +A completed learning project implementing a small neural network directly in Python, C++, and C#, without an ML framework. The exercise explores forward propagation, backpropagation, and momentum updates on the four-case XOR problem. -This repository serves as a multi-language parent container linking the independent language implementations via Git submodules. +The Python implementation is the reproducible reference for this closeout. C++ and C# remain historical ports with different initialization and training settings; this repository does not establish identical results across languages. There is no active feature roadmap. -## Repository Structure +Read the [technical retrospective](docs/RETROSPECTIVE.md) for the scope, checks, and limitations. -* **`cpp/`** — C++ implementation (`Cpp-Neural-Network`) -* **`csharp/`** — C# implementation (`C-Sharp-Neural-Network`) -* **`python/`** — Python implementation (`Python-Neural-Network`) +## Clone ---- +The language implementations are separate repositories pinned as Git submodules. Public HTTPS URLs allow cloning without configuring GitHub SSH keys: -## How to Clone +```sh +git clone --recurse-submodules https://github.com/lonlydwolf/XOR-First-Principles-Network.git +cd XOR-First-Principles-Network +``` -Because this repository utilizes Git submodules, standard cloning will leave the language directories empty. Use the `--recurse-submodules` flag to fetch the parent repository and all sub-repositories simultaneously: +For an existing checkout, initialize or refresh the submodules at the revisions recorded by this repository: -```bash -git clone --recurse-submodules [https://github.com/lonlydwolf/xor-first-principles-network.git](https://github.com/lonlydwolf/xor-first-principles-network.git) \ No newline at end of file +```sh +git submodule sync --recursive +git submodule update --init --recursive +``` + +## Run the Python reference + +Use Python 3.12 or later; the example and tests use only the standard library. From this repository's root: + +```sh +python3 python/examples/xor_demo.py --seed 0 +python3 -m unittest discover -s python/tests -v +``` + +On Windows, use `py -3` in place of `python3` if that is how Python is installed. + +The example reads the checked-in 4,000-example training sequence, seeds weight initialization, and prints predictions for `00`, `01`, `10`, and `11` after training. Classification uses a threshold of `0.5`. It does not rewrite the historical training-output file. Repeating a seed makes the experiment reproducible within the same runtime; exact floating-point values can vary across runtimes. + +The tests check XOR classification at fixed seeds, compare a backpropagation update with finite-difference gradients, and exercise file paths from a different working directory. The GitHub Actions workflow runs the reference checks on Linux and Windows. These checks cover the Python implementation, not numerical equivalence with the other ports. + +XOR contains only four possible input pairs. Demonstrating convergence on those pairs verifies this small exercise; it is not a benchmark of generalization to unseen tasks. + +## Repository structure + +- [`python/`](python): Python reference, deterministic example, and regression tests. See its [README](python/README.md) for the original trainer's file-output behavior. +- [`cpp/`](cpp): historical C++ implementation and Visual Studio project. The source compiled during review, but its full training run was not validated. +- [`csharp/`](csharp): historical C# implementation targeting .NET Core 3.1. Its expected input-data fixture is not included in the pinned tree; its run was not validated. + +All implementations use `tanh` activation and a fixed `+1` bias at each non-input neuron. Biases are not learned. The Python reference has a `[2, 4, 1]` topology for the checked-in dataset. + +## Limits and historical differences + +- C++ uses different momentum and random-initialization settings from Python and C#. No cross-language parity test is included. +- The C++ smoothed-error accumulator starts uninitialized. Its logged error is not a validated metric, even if the source compiles. +- The C++ and C# error calculations need attention before expanding to multiple output neurons. +- The parent repository collects earlier implementations whose pinned history dates to 2020. This closeout makes the Python exercise easier to reproduce; it does not turn the project into a general-purpose neural-network library. + +Changes to language code belong in the corresponding repository. This parent records the reviewed submodule revisions and provides the common entry point. diff --git a/docs/RETROSPECTIVE.md b/docs/RETROSPECTIVE.md new file mode 100644 index 0000000..529a35b --- /dev/null +++ b/docs/RETROSPECTIVE.md @@ -0,0 +1,29 @@ +# A reproducible neural-network fundamentals exercise + +This project contains direct implementations of a small fully connected network in Python, C++, and C#. It preserves an earlier learning exercise and makes one reference implementation easy to inspect and run. It does not claim production readiness or measured improvements over an ML library. + +## What the implementation exposes + +The neuron and network classes make the calculations visible: weighted sums, `tanh` activation, output and hidden-layer gradients, and updates with momentum. The checked-in Python dataset specifies two inputs, four hidden neurons, and one output. + +For the single-output reference, the gradient check uses the loss `L = 0.5 * (prediction - target)^2`. The derivative of `tanh` is `1 - output^2`. On the initial update, momentum contributes zero, so a weight's update should equal the negative numerical loss gradient multiplied by the learning rate. Comparing every weight against a finite-difference estimate checks the interaction of forward propagation and backpropagation without reimplementing the same analytic formula as the test oracle. + +The fixed `+1` neuron bias is a simplification of this implementation. There are no trainable bias parameters. The four XOR inputs are both the task and the evaluation cases, so successful classification is evidence of learning this truth table, not broader generalization. + +## Why the closeout focuses on Python + +The historical code had useful behavior behind an unreliable entry point. Windows-specific path concatenation prevented ordinary Python startup on macOS. The parent clone command also contained Markdown link syntax, while SSH submodule URLs imposed an unnecessary authentication prerequisite for public source. + +The closeout repairs those entry points, adds a seeded example that leaves tracked training logs alone, and adds regression checks for convergence, numerical gradients, and paths. The neural-network algorithm remains the historical implementation. The example and tests require no model download or third-party Python packages. + +## Why the language ports are not called equivalent + +The ports explore the same general algorithm, but they do not use a shared initial-weight fixture or the same momentum. They also have different execution prerequisites. Describing their results as identical would require controlled inputs, matched settings, and comparison within an explicit numerical tolerance. + +C++ source compilation was checked in the October 2026 review; the full executable was not run. Its uninitialized smoothed-error accumulator remains a known limitation. C# was not executed, and its expected data fixture is absent. Those implementations remain historical reference material rather than newly validated examples. + +## What the evidence supports + +A reviewer can now run the Python exercise, inspect all four predictions, and run tests that would detect meaningful regressions in weight updates and classification. The test suite is intentionally small and tied to the exercise's claims. It does not establish that arbitrary network topologies, new datasets, or the other language ports behave correctly. + +The broader lesson is that a compact fundamentals project benefits from explicit assumptions and reproducible results. Its value comes from making the algorithm and its limits understandable. Further feature development is not planned. diff --git a/python b/python index d317917..dcd2301 160000 --- a/python +++ b/python @@ -1 +1 @@ -Subproject commit d317917fae80a8d46351664493fe789f450cd0f9 +Subproject commit dcd23014649014a21a1d19191d9c020cac8e4ef9