twincher 0.1.0__tar.gz

twincher-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Build artifacts
+/build/
+/dist/
+/wheelhouse/
+*.egg-info/
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+*.o
+*.a
+*.so
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.nox/
+.ruff_cache/
+.mypy_cache/
+
+# Outputs of tutorials, tests and benchmarks
+/tutorial/output_*/
+twincher_output/
+*.twc
+*.tw
+
+# Editors and OS
+.vscode/
+.idea/
+.DS_Store

twincher-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-02
+
+First public release.
+
+### Added
+
+- Computational core in C++ with a CPU backend (OpenMP) and an optional GPU backend (CUDA), accessible through `twincher.Shuttle`. It supports PyTorch tensors, NumPy arrays and CuPy arrays.
+- The hyper-sail architecture (`hs`): loss terms `HSLoss` and `HSNoiseLoss`, solver `HSSolver` and monitor `HSMonitorP2`.
+- Training and evaluation: `Learner`, `solver()`, `Verifier`, `noise_check()`, `monitor()` and `TimeMonitor`.
+- A registry for adding architectures (`register()`).
+- File format for trained twinchers (`.twc`) with a format version.
+- Tutorials: spiral and double Gaussian.
+
+[0.1.0]: https://github.com/arkady-gonoskov/twincher/releases/tag/v0.1.0

twincher-0.1.0/CITATION.cff

@@ -0,0 +1,33 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite the article below."
+title: "twincher"
+type: software
+abstract: >-
+  Python package with a C++/CUDA core that implements twinchers: trainable
+  diffeomorphic representations for fast, never-stalling solution of inverse
+  problems.
+authors:
+  - family-names: Gonoskov
+    given-names: Arkady
+    email: contact@twincher.ai
+version: 0.1.0
+date-released: 2026-10-02
+license: AGPL-3.0-only
+url: "https://www.twincher.ai"
+repository-code: "https://github.com/arkady-gonoskov/twincher"
+keywords:
+  - inverse problems
+  - diffeomorphism
+  - representation learning
+  - machine learning
+preferred-citation:
+  type: article
+  title: "Twincher: Bijective Representation Learning for Robust Inversion of Continuous Systems"
+  authors:
+    - family-names: Gonoskov
+      given-names: Arkady
+  journal: "arXiv preprint arXiv:2605.13470"
+  year: 2026
+  month: 5
+  doi: "10.48550/arXiv.2605.13470"
+  url: "https://arxiv.org/abs/2605.13470"

twincher-0.1.0/CLA.md

@@ -0,0 +1,71 @@
+# Twincher Contributor License Agreement
+
+Version 1.0
+
+Thank you for your interest in contributing to Twincher. Twincher is distributed under the GNU Affero General Public License, version 3 (AGPL-3.0). It is also available under separate commercial licenses. So that contributions can be distributed on both of these terms, the Project Owner asks all contributors to accept this Contributor License Agreement (the "Agreement"). Under this Agreement you keep the copyright in your Contributions. You grant the Project Owner a license to use them, as described below.
+
+Please read this Agreement carefully. It applies both to individuals and to legal entities (such as companies) that contribute to the Project.
+
+## 1. Definitions
+
+**"Project Owner"** means Arkady Gonoskov, together with his successors and assigns. This includes any legal entity to which the rights in the Project are transferred.
+
+**"Project"** means the software, documentation and other materials known as Twincher that are owned and managed by the Project Owner, including their source code repositories.
+
+**"You"** (or **"Your"**) means the individual or legal entity that accepts this Agreement. For legal entities, "You" includes the entity and all other entities that control it, are controlled by it, or are under common control with it. For this definition, "control" means ownership of more than fifty percent (50%) of the voting securities or other ownership interests, or the power to direct the management and policies of the entity.
+
+**"Contribution"** means any original work of authorship that You submit to the Project Owner for inclusion in the Project, including any modifications of or additions to existing work. "Submit" means any form of electronic or written communication sent to the Project Owner or its representatives. Examples include pull requests, patches, issues and discussions in the Project's repositories, as well as e-mail. It does not include communication that You conspicuously mark, or otherwise designate in writing, as "Not a Contribution".
+
+## 2. Copyright license
+
+You grant to the Project Owner, and to recipients of software distributed by the Project Owner, a copyright license with the following properties: perpetual, worldwide, non-exclusive, no-charge, royalty-free and irrevocable. The license allows them to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense and distribute Your Contributions and such derivative works.
+
+Such distribution and sublicensing may be under any license terms, including open source licenses as well as proprietary or commercial licenses.
+
+## 3. Patent license
+
+You grant to the Project Owner, and to recipients of software distributed by the Project Owner, a patent license with the following properties: perpetual, worldwide, non-exclusive, no-charge, royalty-free and irrevocable (except as stated in this section). The license allows them to make, have made, use, offer to sell, sell, import and otherwise transfer Your Contributions.
+
+This license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution alone, or by the combination of Your Contribution with the Project to which it was submitted.
+
+If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that Your Contribution, or the Project to which You contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution terminate as of the date such litigation is filed.
+
+## 4. Commitment to open source availability
+
+When the Project Owner distributes a Contribution as part of the Project, the Project Owner agrees to also make it available under the open source license or licenses under which the Project is publicly distributed on the date the Contribution was submitted. This commitment does not limit the rights granted in Sections 2 and 3.
+
+## 5. Moral rights
+
+To the fullest extent permitted by applicable law, You waive, and agree not to assert, any moral rights You may have in Your Contributions against the Project Owner or recipients of software distributed by the Project Owner.
+
+## 6. Your representations
+
+You represent that:
+
+1. You are legally entitled to grant the licenses in this Agreement.
+2. If Your employer, or any other party, has rights to intellectual property that You create, including Your Contributions, then one of the following is true: You have received permission to make Contributions on its behalf; that party has waived such rights for Your Contributions; or that party has accepted this Agreement.
+3. Each of Your Contributions is Your original creation. It includes complete details of any third-party license or other restriction (including related patents and trademarks) that You are personally aware of and that is associated with any part of the Contribution.
+4. If You wish to submit work that is not Your original creation, You will submit it separately from any Contribution. You will identify the complete details of its source and of any license or other restriction that You are personally aware of, and conspicuously mark the work as "Submitted on behalf of a third party: [named here]".
+
+If You accept this Agreement on behalf of a legal entity, You represent that You are authorized to do so.
+
+You agree to notify the Project Owner of any facts or circumstances of which You become aware that would make these representations inaccurate in any respect.
+
+## 7. Retained rights
+
+You keep all right, title and interest in Your Contributions. Apart from the licenses granted in this Agreement, You may use Your Contributions for any purpose.
+
+## 8. No obligation and no warranty
+
+The Project Owner is not obligated to use or include any Contribution in the Project.
+
+You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. This includes, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+## 9. Acceptance
+
+You accept this Agreement in one of two ways:
+
+- by confirming it electronically through the mechanism provided in the Project's repository, for example by a comment on a pull request; or
+- by sending a signed copy to contact@twincher.ai.
+
+Once accepted, this Agreement applies to all Contributions You have submitted and will submit to the Project.

twincher-0.1.0/CMakeLists.txt

@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2025-2026 Arkady Gonoskov
+
+# Builds the compiled core of twincher: the Python extension module twincher._core.
+# Normally invoked through pip (scikit-build-core), see pyproject.toml and CONTRIBUTING.md.
+
+cmake_minimum_required(VERSION 3.24)
+
+# Compile CUDA code for the GPU(s) of the build machine unless architectures are given
+# explicitly, e.g. via the environment variable CUDAARCHS="86;120" or
+# -DCMAKE_CUDA_ARCHITECTURES="86;120".
+if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES AND NOT DEFINED ENV{CUDAARCHS})
+    set(CMAKE_CUDA_ARCHITECTURES native)
+endif()
+
+project(twincher LANGUAGES CXX)
+
+# GPU backend: AUTO builds it if a CUDA compiler (nvcc) is found, and otherwise builds a
+# CPU-only package with a warning. ON makes the CUDA compiler mandatory, OFF disables it.
+set(TWINCHER_CUDA AUTO CACHE STRING "Build the CUDA backend (AUTO, ON or OFF)")
+set_property(CACHE TWINCHER_CUDA PROPERTY STRINGS AUTO ON OFF)
+set(TWINCHER_WITH_CUDA OFF)
+if(NOT TWINCHER_CUDA STREQUAL "OFF")
+    include(CheckLanguage)
+    check_language(CUDA)
+    if(CMAKE_CUDA_COMPILER)
+        enable_language(CUDA)
+        set(TWINCHER_WITH_CUDA ON)
+    elseif(TWINCHER_CUDA STREQUAL "ON")
+        message(FATAL_ERROR "TWINCHER_CUDA=ON, but no CUDA compiler (nvcc) was found.")
+    else()
+        message(WARNING
+            "No CUDA compiler (nvcc) was found: twincher is built without GPU support. "
+            "To enable it, make nvcc available (e.g. add the bin directory of the CUDA toolkit "
+            "to PATH, or set CUDACXX) and reinstall.")
+    endif()
+endif()
+message(STATUS "twincher: CUDA backend ${TWINCHER_WITH_CUDA}")
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CUDA_STANDARD 17)
+set(CMAKE_CUDA_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+# compile_commands.json in the build directory, for code editors (IntelliSense) and tools
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+    set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
+endif()
+
+option(TWINCHER_NATIVE_ARCH
+    "Optimize host code for the CPU of the build machine (-march=native); the result is not portable" OFF)
+option(TWINCHER_BUILD_BENCHMARKS "Build C++ benchmark executables" OFF)
+
+# Version string reported by info(); scikit-build-core provides it from pyproject.toml
+if(DEFINED SKBUILD_PROJECT_VERSION)
+    set(TWINCHER_VERSION "${SKBUILD_PROJECT_VERSION}")
+else()
+    set(TWINCHER_VERSION "dev")
+endif()
+
+if(NOT MSVC)
+    add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-Wall>)
+endif()
+if(TWINCHER_NATIVE_ARCH)
+    add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-march=native>)
+endif()
+
+# ---------------------------------------------------------------------------------------
+# Dependencies
+# ---------------------------------------------------------------------------------------
+find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module)
+if(NOT DEFINED SKBUILD AND NOT DEFINED pybind11_DIR)
+    # plain CMake build: use pybind11 installed in the active Python environment
+    execute_process(
+        COMMAND "${Python_EXECUTABLE}" -m pybind11 --cmakedir
+        OUTPUT_VARIABLE pybind11_DIR
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        ERROR_QUIET
+    )
+endif()
+find_package(pybind11 CONFIG REQUIRED)
+# OpenMP parallelizes the CPU backend; without it, the CPU backend runs in a single thread
+find_package(OpenMP COMPONENTS CXX)
+if(NOT OpenMP_CXX_FOUND)
+    message(WARNING "OpenMP was not found: the CPU backend of twincher will run in a single thread.")
+    if(NOT MSVC)
+        add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-Wno-unknown-pragmas>)
+    endif()
+endif()
+
+# ---------------------------------------------------------------------------------------
+# CUDA backend (static library linked into the extension module)
+# ---------------------------------------------------------------------------------------
+if(TWINCHER_WITH_CUDA)
+    find_package(CUDAToolkit REQUIRED)
+    add_library(twincher_cuda STATIC src/shuttle_gpu.cu)
+    target_include_directories(twincher_cuda
+        PUBLIC  ${PROJECT_SOURCE_DIR}/include
+        PRIVATE ${CUDAToolkit_INCLUDE_DIRS}/cccl
+    )
+    # The static CUDA runtime makes the module independent of the location/version of
+    # libcudart.so at run time; only the NVIDIA driver is needed.
+    target_link_libraries(twincher_cuda PUBLIC CUDA::cudart_static)
+    target_compile_definitions(twincher_cuda PUBLIC TWINCHER_WITH_CUDA)
+    set_target_properties(twincher_cuda PROPERTIES CUDA_SEPARABLE_COMPILATION OFF)
+    # Useful options for development and profiling of CUDA kernels:
+    #   -lineinfo              source line information for Nsight Compute
+    #   -Xptxas -v             report register and shared memory usage
+    #   --maxrregcount=60      limit the number of registers per thread
+    # target_compile_options(twincher_cuda PRIVATE $<$<COMPILE_LANGUAGE:CUDA>:-lineinfo>)
+endif()
+
+# ---------------------------------------------------------------------------------------
+# Python extension module twincher._core
+# ---------------------------------------------------------------------------------------
+pybind11_add_module(_core src/bindings.cpp src/common.cpp)
+target_include_directories(_core PRIVATE ${PROJECT_SOURCE_DIR}/include)
+if(OpenMP_CXX_FOUND)
+    target_link_libraries(_core PRIVATE OpenMP::OpenMP_CXX)
+endif()
+if(TWINCHER_WITH_CUDA)
+    target_link_libraries(_core PRIVATE twincher_cuda)
+endif()
+target_compile_definitions(_core PRIVATE TWINCHER_VERSION="${TWINCHER_VERSION}")
+install(TARGETS _core LIBRARY DESTINATION twincher)
+
+# ---------------------------------------------------------------------------------------
+# Benchmarks (optional, not installed)
+# ---------------------------------------------------------------------------------------
+if(TWINCHER_BUILD_BENCHMARKS)
+    add_executable(bench_cpu benchmarks/bench_cpu.cpp)
+    target_include_directories(bench_cpu PRIVATE ${PROJECT_SOURCE_DIR}/include)
+    if(OpenMP_CXX_FOUND)
+        target_link_libraries(bench_cpu PRIVATE OpenMP::OpenMP_CXX)
+    endif()
+endif()

twincher-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,133 @@
+# Contributing to Twincher
+
+Thank you for considering a contribution to Twincher! Bug reports, suggestions and pull requests are welcome.
+
+## License and Contributor License Agreement
+
+Twincher is distributed under the [GNU Affero General Public License, version 3](LICENSE) (AGPL-3.0). It is also available under separate commercial licenses. So that contributions can be distributed on both of these terms, every contributor needs to accept the [Contributor License Agreement](CLA.md) (CLA) before their first pull request can be merged.
+
+The CLA is a license, not a transfer of ownership: you keep the copyright in your contributions. When you make a contribution to the Project, the Project Owner also commits to keep it available under the open source license of the Project (see Section 4 of the CLA).
+
+You can accept the CLA in either of two ways:
+
+- **Individuals:** confirm it in a comment on your pull request, when asked to do so.
+- **Companies and other organizations:** send a signed copy to contact@twincher.ai.
+
+If you contribute as part of your job, please make sure your employer agrees. Your employer may need to accept the CLA as an organization.
+
+## Development setup
+
+Requirements:
+
+- Linux (or WSL);
+- Python >= 3.10;
+- a C++17 compiler with OpenMP support;
+- for the GPU backend, the CUDA toolkit (`nvcc`).
+
+CMake and Ninja are installed into the virtual environment below.
+
+Create a virtual environment and install the build tools into it:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install scikit-build-core pybind11 cmake ninja
+```
+
+Then install twincher in editable mode:
+
+```bash
+pip install --no-build-isolation -Ceditable.rebuild=true -Cbuild-dir=build/editable -e ".[dev]"
+```
+
+In this mode, the Python sources are used directly from `python/twincher`. After you change the C++/CUDA sources, the extension module is rebuilt automatically at the next `import twincher`. The build files are kept in `build/editable`, so rebuilds are incremental.
+
+### Running the tests
+
+```bash
+python -m pytest                          # all tests (about one minute)
+python -m pytest -m "not e2e"             # unit tests only (a few seconds)
+python -m pytest -rP tests/test_core.py   # also show the values printed by the tests
+```
+
+The tests use the installed package, so they can be run from any environment in which twincher is installed.
+
+Tests that need a GPU are marked with `gpu`. They are skipped automatically if twincher cannot use a GPU: either there is none, or twincher was built without CUDA. The GPU tests with CuPy arrays are additionally skipped if CuPy is not installed (`pip install cupy-cuda13x`, matching your version of CUDA).
+
+| Tests | Content |
+|---|---|
+| `test_core.py` | The computational core: CPU against finite differences, GPU against CPU |
+| `test_shuttle.py`, `test_errors.py`, `test_file_format.py` | The Python wrapper `Shuttle`, error handling, `.twc` files |
+| `test_learner.py`, `test_package.py` | `Learner`, solver and `Verifier` on a tiny problem; imports, registry, utilities |
+| `test_e2e_spiral.py` | End-to-end (marked `e2e`): training on the spiral problem and solving the inverse problem |
+
+### Continuous integration
+
+For every push to `main` and every pull request, GitHub Actions ([.github/workflows/tests.yml](.github/workflows/tests.yml)) runs three jobs:
+
+- **Tests:** on Python 3.10 to 3.14, with the CPU-only package.
+- **CUDA build:** compiles the CUDA backend in a container with the CUDA toolkit.
+- **Source distribution:** builds the source distribution and tests the package installed from it.
+
+The runners of GitHub have no GPU, so the GPU tests are not run there. Please run the tests on a machine with a GPU before submitting changes of the C++/CUDA core.
+
+The workflow [.github/workflows/release.yml](.github/workflows/release.yml) publishes releases, see [Releasing](#releasing).
+
+### Documentation
+
+- [README.md](README.md) is the main documentation, shown on GitHub. Formulas are written as ```` ```math ```` blocks and inline as `` $`...`$ ``: GitHub passes these to MathJax unchanged, whereas `$...$` and `$$...$$` are subject to Markdown processing (backslashes and underscores are lost).
+- [docs/pypi_description.md](docs/pypi_description.md) is the text of the package page on PyPI, which cannot render formulas and the images of the README. Its example is the same as in the section "Getting started" of the README; please keep them in sync.
+- [CHANGELOG.md](CHANGELOG.md) lists notable changes for each release.
+
+### Plain CMake build (C++ benchmarks)
+
+With the virtual environment activated:
+
+```bash
+cmake -S . -B build/cmake -G Ninja -DTWINCHER_BUILD_BENCHMARKS=ON
+cmake --build build/cmake
+build/cmake/bench_cpu 0 6    # mode 0 (inference), 6 threads
+```
+
+### Build options
+
+The following CMake options can be passed to pip as `-Ccmake.define.<OPTION>=<VALUE>`:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `TWINCHER_CUDA` | `AUTO` | GPU backend. `AUTO`: build it if a CUDA compiler (nvcc) is found, otherwise build CPU-only with a warning. `ON`: require it. `OFF`: disable it. |
+| `CMAKE_CUDA_ARCHITECTURES` | `native` | GPU architectures to compile for, e.g. `"86;120"`. The environment variable `CUDAARCHS` can be used instead. |
+| `TWINCHER_NATIVE_ARCH` | `OFF` | Optimize host code for the CPU of the build machine (`-march=native`). The result is not portable. |
+| `TWINCHER_BUILD_BENCHMARKS` | `OFF` | Build the C++ benchmark executables. |
+
+### Building distributions
+
+```bash
+pip install build
+python -m build    # creates dist/twincher-<version>.tar.gz and a wheel
+```
+
+## Releasing
+
+Releases are published on PyPI as source distributions by the workflow [.github/workflows/release.yml](.github/workflows/release.yml), using trusted publishing (no API tokens).
+
+### For each release
+
+1. Make sure that the tests pass on GitHub (workflow *Tests*) and locally on a machine with a GPU (`python -m pytest`).
+2. Set the new version in `pyproject.toml` and `CITATION.cff` (also `date-released`), and move the changes in `CHANGELOG.md` under a heading with the version and date. Commit and push to `main`.
+3. Optionally, make a trial run on TestPyPI: in the *Actions* tab, run the workflow *Release* manually. Then install from TestPyPI in a new environment:
+
+   ```bash
+   pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ twincher
+   ```
+
+   TestPyPI, like PyPI, accepts each version only once; for repeated trials use pre-release versions such as `0.2.0rc1`.
+4. Create a release on GitHub with the tag `v<version>` (for example `v0.1.0`), with the changes from `CHANGELOG.md` as description. Publishing the release starts the upload to PyPI.
+
+## Reporting issues
+
+When reporting a bug, please include:
+
+- the Twincher version (`python -c "import twincher; print(twincher.__version__)"`);
+- your operating system, Python version, and CUDA version (if relevant);
+- a minimal script that reproduces the problem.