Exudyn developer documentation

Developer-facing notes. Users start at README.rst and INSTALL.txt in the repository root, or at the online documentation.

document	contents
ARCHITECTURE.md	the C++ internals: items, the C/Main/Visualization split, the object factory, modules, solvers
CODING_STYLE.md	naming, abbreviations, file headers, how to report an error from C++ (§10), what is deprecated
WORKFLOW.md	issue tracker, versioning, the four commit gates
NEW_ITEM.md	how to set up a new item: the definition, what is generated, the C++, what to run
GUI_MANUAL_CHECK.md	the manual check of the render window and the dialogs before a release, per platform
../../definitions/README.md	the item and structure definitions as Python, and the function declaration library
../../tools/generators/README.md	the new generator code and how to re-emit the definitions
exudynRevisionInfo2026.md	general information on the v1.11.0 → v2.0 restructuring: rules, facts, decisions
exudynRevisionPlan2026b.md	the plan that is open: what the revision did not finish and what comes next, by group RG1 … RG15
exudynRevisionPlan2026.md	the finished plan of the 2026 revision, phases R0 … R11 — a record; the revision completed as 1.12
exudynRevisionLog2026b.md / exudynRevisionLog2026.md	what each closed step actually turned out to be — the second is closed with its plan, the first is where the work of revision2026b is written up
../../CONTRIBUTING.md	how to contribute from outside
CLAUDE.md	the working contract for Claude Code sessions

Repository layout

setup.py                                  the real build
exudynTemplate.sln                        VS2022 solution template (exudynPython.pyproj + cppsrc.vcxproj)
msvc/cppsrc.vcxproj                       the C++ source list; sources.json is generated from it
src/                                      hand-written C++: Graphics ImplMarkers ImplNodes ImplObjects
                                          Linalg Main Pymodules Solver System Tests Utilities
src/Autogenerated/                        generated C++ - never edit by hand
definitions/, tools/generators/          the generator input and the generators
python/exudyn/                            the shipped Python package
python/TestModels/                        the test models, nothing else
python/PerformanceModels/                 the performance models
python/MiniExamples/                      the generated mini examples
python/Examples/                          the examples
python/testing/                           the runners: runTestSuite.py and the rest
python/logs/                              testmodels/ examples/ performance/ tmp/
index.md                                  the table of contents of the documentation, hand-written: what comes in which order
docs/manual/                              the user manual, hand-written Markdown
docs/generated/                           the generated documentation (emitters, issue tracker)
docs/figures/                             the images of the documentation
docs/howTo/                               loose how-to notes, see below
tools/issueTracker/                       issue tracker and version source of truth
tools/exudev/                             the dev driver: build, test, docs, release

Building and running

Three pages, in the order a new developer needs them:


GETTING_STARTED.md	from nothing: clone, environment, `setupLocalWorkspace.py`, first build, first test run
BUILD.md	the build itself, per platform, and what to do when it does not work
GIT.md	branches, commit messages, pull, push, merge, and what a contribution provides

Editors. The everyday work happens in VS Code - the Python package, the definition files, the documentation, and Claude Code. Visual Studio 2022 is the debugger: stepping from a Python script into a C++ item’s ComputeODE2LHS with one debugger is the project’s most valuable development capability and is protected by design. tools/setupLocalWorkspace.py prepares both.

The driver: one command, exudev - exudev --help, and exudev -n <command> to see what a command would run without running it. Its commands are in tools/exudev/README.md.

Entry points worth knowing:

src/Pymodules/PybindModule.cpp — module creation.
src/Main/MainObjectFactory.h/.cpp — item creation behind mbs.AddNode(...); dispatch is on the objectType string from the Python dict, through a runtime class-factory registry.

How-to notes

docs/howTo/ was cut from 26 loose .txt files to 8 in the 2026-09 cleanup. Anything referring to VS2017/VS2019, 32-bit builds, Python ≤ 3.7 or the pre-WSLg X-server era was deleted; the specifics worth keeping were lifted into buildQuirks.md. The originals remain in git history, in the archived internal repository and on GitHub.

Three of them are pages of the documentation, because a user or a first-time contributor needs them:

file	what it is for
condaEnvironments.md	environment recipes, the package→feature map, the scipy pin
sphinxDocs.md	building the documentation locally

The other five are maintainer notes: they are in the repository, and they are linked here to GitHub rather than to a page, because they are not published (#2585 — exclude_patterns in conf.py).

file	what it is for
buildQuirks.md	traps that cost real time: MSVC↔GCC flags, `/bigobj`, ABI tags, debugging a startup crash
gccVsMsvcTraps.md	what MSVC accepts and GCC does not, and why
visualStudio2022.md	VS2022 install specifics and `dumpbin /version`
convertVideosFfmpeg.md	producing the demo animations
matplotlibExamples.md	plotting recipes used in examples

macOS setup is covered in docs/manual/gettingStarted.md, not here.

Invariants

These are differentiators, not technical debt. Every restructuring step preserves them (plan §7):

Mixed Python/native debugging in VS2022 - the capability, not which editor is primary; the everyday work happens in VS Code.
The setuptools-based fast build.
No heavy C++ dependencies; vendored headers.
The hard C++/Python split with dict-based validated interfaces.
Runtime dependencies stay at numpy only. Development-only tools are unconstrained.