---

name: code-generation description: "Choose Brian2 runtime and C++ standalone code-generation targets, manage builds and reusable runs, and recover compiler, cache, result-directory, and optional GSL failures." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Brian2 code generation

Use this route when the task names prefs.codegen.target, Cython, NumPy code objects, set_device, cpp_standalone, a compiler/build directory, repeated standalone runs, run_args, or GSL integration. This sub-skill is written for Brian2 2.9.0 and Python >=3.12.

Route quickly

1. Ordinary runtime simulation: keep the default runtime device. Start with prefs.codegen.target = "auto"; it prefers Cython when its test compilation succeeds and otherwise falls back to NumPy with a warning. Choose "numpy" explicitly when compiler setup is unavailable or a reproducible no-compiler fallback is more important than speed.
2. Compiled runtime: choose prefs.codegen.target = "cython" only after Cython and a working C++ compiler are available. The first use compiles and caches extensions; later compatible code can reuse the cache.
3. Standalone project: call set_device("cpp_standalone") before model construction. Use the default build_on_run=True for one final run; use build_on_run=False for multiple run statements or a build/reuse loop. device.build controls generation, compilation, and optional first execution: compile=False writes a project but cannot run it, while run_args is forwarded to that first execution. Read standalone-workflows.md before changing a runtime script.
4. Reuse: build once with device.build(run=False) and call device.run(run_args=..., results_directory=...) for subsequent full executions. run_args accepts VariableView/TimedArray mappings or command-line assignment lists; result directories are relative to the project and must be unique when outputs are retained or concurrent. The model and externally defined constants are not generally mutable after compilation; use equation variables with suitable flags and run_args instead.
5. Optional GSL: treat method="gsl" and the gsl_* methods as an optional native-library path. Runtime GSL needs Cython plus GSL; standalone also needs GSL headers and libraries. If unavailable, use a supported non-GSL state updater and record the numerical/feature limitation.

Operating guardrails

• get_device() returns the active device and device is a proxy to it. A set_device call is global to the current process; restore the runtime device when a larger application continues after a standalone section.
• A CPU/package import check proves only Python/package readiness. It does not prove that Cython can compile or that a C++ standalone project can build and run. Treat compiler preparation and the final native build as separate gates.
• Standalone writes generated sources, a binary, and result files to a project directory. Use a fresh temporary or uniquely named directory for checks and never reuse a result directory concurrently. device.delete(data=True, ...) targets the active result directory; use a disposable project or explicitly remove older result directories as well.
• State arrays and synaptic indices whose values depend on executed code cannot be inspected during standalone setup. Access them after a successful run; use string expressions for dependent initialization where possible.
• GSL state-updater code is experimental, requires native GSL linkage, is not a NumPy runtime path, and rejects stochastic equations. A non-GSL updater is a functional but potentially non-equivalent fallback; do not claim GSL support without a tiny target-specific compile/run.
• Do not use this route to design neuron/synapse equations, schedule ordinary networks, or explain general preferences. Hand those requests to the corresponding modeling, simulation, or configuration route. Long benchmarks, multiprocessing studies, and large training runs are reference-only here.

Bundled operating references

• api-reference.md: target, device, build, run, cache, and cleanup API facts.
• runtime-targets.md: runtime target selection, Cython prerequisites, NumPy fallback, and cache reuse.
• standalone-workflows.md: one-run, multi-run, run_args, result directories, and standalone limitations.
• optional-backends.md: GSL prerequisites, supported paths, and fallback boundaries.
• troubleshooting.md: install/import, optional-dependency, data/configuration, API, compiler/cache, and workflow failure recovery.

For a safe native smoke after the integrated skill has been prepared, run the bundled script with --help first and then, only with an intentionally prepared compiler, run the default tiny check:

python scripts/standalone_smoke.py --help
python scripts/standalone_smoke.py

The script uses a temporary output directory, a tiny deterministic model, and cleanup. It is not a substitute for a real project build of a user's model.