neuromancer master is a year past its v1.5.6 tag, pins two dependencies exactly, and has no Intel Mac environment file

The branch is roughly a year ahead of the newest published release

The newest release is v1.5.6, tagged 2025-09-26, and v1.5.5 was tagged the same afternoon an hour earlier, so the last release cycle was two tags in one day. The branch itself was last pushed on 2026-10-01, two days before this snapshot. The README title also says v1.5.6 and the packaging metadata reads `version = "1.5.6"`, so nothing inside the tree is confused about which version it is. What that means in practice is a year of divergence between what `pip install neuromancer` gives you and what is in the repository today. For a library whose value is in its example notebooks, that gap matters more than it would for a service: the tutorials in the tree are the current documentation, and the tutorials you get from the package are a year old. There is a RELEASE_NOTES.md at the root, which is where the unreleased work would be described, and no GitHub release entry has been cut since September 2025.

The table of contents advertises an older version than the section it links to

The table of contents on the page numbers seven entries and contains two small errors that both concern versions. Entry three reads What's New in v1.5.3 with the anchor `#whats-new-in-v153`, while the section further down the page is headed What's New in v1.5.6. So the one part of the README most likely to be wrong about what changed is the part whose label and link were never updated past 1.5.3. The numbering also slips: the list runs 1, 2, 3, 4, 5, 6, 6, with both Tutorials and Documentation and User Guides numbered six. Neither error breaks anything, and both are the kind that survives for years in a README nobody re-reads top to bottom. The practical consequence is narrow but real. If you came here to find out what is new, the table of contents tells you the answer belongs to a release two versions back, and the changelog you actually want is RELEASE_NOTES.md.

One documentation link points at a branch that is not the default

Every example notebook link on the page is built from `github.com/pnnl/neuromancer/blob/master/`, which matches the default branch. The NeuroMANCER-GPT Assistant link is built from `github.com/pnnl/neuromancer/blob/develop/assistant/README.md`. One link out of many, on a different branch, for the one feature that is a wrapper around the library rather than an example of it. The assistant directory is present at the repository root, so the content exists somewhere; whether the develop copy is current is exactly what you would have to check before trusting it. This is worth knowing because the assistant is the entry point the README recommends for people who want an LLM to help them write NeuroMANCER code, and a stale branch on that path means the model is being pointed at a different version of the API than the one in the tree.

Two dependencies are pinned to an exact version, and one of them is load bearing

Most of the dependency list uses ranges: `networkx>=3,<4` and `numpy>=1.23,<3.0` with the rest unconstrained. Two entries do not. `plum-dispatch==1.7.3` and `pydot==1.4.2` are pinned to a single version with no range at all. Plum-dispatch is the multiple dispatch library that the symbolic programming interface is built on, so it is not an incidental choice, and pinning it exactly means the symbolic API can only move when NeuroMANCER releases. Pydot is the graphviz binding used to draw the symbolic graphs the Node classes produce, and the same constraint applies in a smaller way. Two more entries are worth noting rather than blaming. `six` is still declared as a direct runtime dependency while the package requires Python 3.9 or later, where a compatibility shim for Python 2 has no purpose, which suggests it is there for a transitive consumer. The version floor is 3.9 and the classifiers stop at 3.12, so a 3.13 interpreter is neither claimed nor excluded.

Three environment files, one of them arm64 only, and a .DS_Store under version control

Manual installation is documented in INSTALLATION.md, and the root carries three environment files: `linux_env.yml`, `windows_env.yml`, and `osxarm64_env.yml`. The macOS one is named for arm64 specifically, so there is no recipe shipped for an Intel Mac, which means the platform with the largest installed base of PyTorch users gets the least prepared environment. That is a small thing and an easy one to work around by hand, but it is the kind of gap that turns into an afternoon. The examples directory also carries a committed `.DS_Store`, the Finder metadata file that no repository should track, which tells you the examples were assembled on a Mac desktop and copied in. The rest of the example tree is organised by mathematical method rather than by application: DAEs, ODEs, PDEs, SDEs, KANs, function encoders, control, parametric programming, plus integration directories for lightning and for a package called psl.

The headline example ends at a comment about sampling parameters

The quick example is the first thing a new user copies, and it stops mid file:

# Neuromancer syntax example for constrained optimization
import neuromancer as nm
import torch

# define neural architecture
func = nm.modules.blocks.MLP(insize=1, outsize=2,
                             linear_map=nm.slim.maps['linear'],
                             nonlin=torch.nn.ReLU, hsizes=[80] * 4)
# wrap neural net into symbolic representation via the Node class: map(p) -> x
map = nm.system.Node(func, ['p'], ['x'], name='map')

# define decision variables
x = nm.constraint.variable("x")[:, [0]]
y = nm.constraint.variable("x")[:, [1]]
# problem parameters sampled in

The last line is a comment announcing that problem parameters get sampled, and the sampling code, the objective, the constraint, and the solver are all absent. Two details in what is shown are worth copying carefully rather than blindly. The Node is assigned to a variable called `map`, which shadows Python's builtin, so any later code in that file cannot use the builtin. And both decision variables are carved out of the same Node output by indexing it twice, `variable("x")[:, [0]]` and `variable("x")[:, [1]]`, which is the idiom to follow if you want the network's two outputs to become two separate symbols.

A drop-in replacement for the core System class, and a fix for a dependency nobody declares

The v1.5.6 notes list one new class, `SystemPreview`, described as a drop-in replacement for the `System` class that adds preview horizon functionality, and the corresponding new example is DPC with a preview horizon. Preview horizon is also what the mixed-integer DPC example for a thermal system exercises, so the feature is aimed squarely at building control where you want to reason about a window of future measurements. The other two notes are housekeeping: unit tests brought up to date, and a bug fixed where an mlflow dependency was creating conflicts in Google Colab. That second one is the interesting entry, because mlflow does not appear in the declared dependency list at all. It arrives transitively, and the examples tree carries a `lightning_integration_examples` directory while `lightning` is a declared dependency, so the fix landed at the symptom rather than at the edge. A Colab user can still hit the conflict depending on what else is in the notebook environment.

Editorial conclusion

Reach for this when your problem is genuinely a constrained parametric optimization you want inside a training loop, and when you already live in PyTorch and can tolerate a research library's release cadence. Two things decide whether it fits. Pin your own versions of plum-dispatch and pydot, because the package pins both exactly and anything you need that requires a different plum-dispatch will collide at install time. And read the release notes rather than the branch, since master carries about a year of changes past v1.5.6 and pip will give you the tag, not the branch. If you are reproducing a published result, check which of the two you are running before you compare numbers.

Frequently asked questions

Official sources

1. Issues
2. pnnl/neuromancer on GitHub
3. Project website
4. README
5. Releases