---

name: configuration-and-troubleshooting description: "Install and validate Brian2 2.9.0 environments, configure preferences, caches, and logging, and triage import, compiler, optional-dependency, and common runtime failures." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Configuration and troubleshooting

Use this route when Brian2 cannot be imported, a package/compiler prerequisite is unclear, a preference unexpectedly changes the code-generation or cache configuration, or a log is needed to classify a failure. This route covers Brian2 2.9.0 with Python >=3.12 and the brian2 import root.

Route quickly

1. Establish identity and baseline. From the directory containing this sub-skill's bundled scripts/ directory (or by passing that script's relative path), run python scripts/check_brian2_env.py. Confirm Python

   =3.12, distribution Brian2==2.9.0, every declared base dependency and version constraint, and that an incomplete source checkout is not shadowing the intended installation. The checker is read-only and does not reveal executable or cache paths.

2. Repair installation before configuration. Follow installation in an isolated environment. Do not mix a checkout import with a separately installed distribution. If the checker reports a required import or version failure, fix that first and retest in a fresh interpreter.
3. Inspect effective preferences and cache state. Read preferences and cache before changing prefs.codegen.target, compiler settings, or Cython cache settings. The current-directory preference file overrides the user preference file.
4. Capture evidence and classify the first failure. Use troubleshooting to preserve the exception, Python/package versions, target, compiler names, relevant preferences, and Brian debug-log information before retrying or clearing a cache.
5. Choose the smallest validation. A NumPy-target tiny model checks core Python execution. A Cython or C++ build is a separate native gate and can write cache/project files; run it only as an explicitly approved local check.

Scope and routing boundaries

This route owns installation, importability, required package presence, compiler/Cython prerequisite diagnosis, preference-file precedence and validation, cache ownership/permissions, logging diagnostics, and generic failure triage. It does not own detailed code-generation target selection, generated-code APIs, standalone project design, model equations, scheduling, or workflow-specific failures. After recording environment facts here, route those details to code-generation, modeling, simulation-and-recording, recording, spatial-models, or units-and-equations, respectively.

Optional packages are capability boundaries, not automatic requirements:

• SciPy is required for selected NumPy spatial/multicompartment operations; Matplotlib is for plotting; Pandas is for state import/export formats; IPython/Jupyter is for interactive notebooks; and brian2tools is a separate visualization/analysis package.
• GSL support means a native GSL installation with headers/libraries as well as Brian's integration; a Python import or library-name probe alone cannot prove it. Route GSL state-updater/code-generation use to code-generation.
• pytest>=8 is the test extra needed by brian2.test(). A full test run is not the default response to a user-model failure.

Safety and acceptance

• Do not install packages, use network commands, compile extensions, clear caches, delete standalone output, or edit preference files during a read-only diagnosis.
• Treat import brian2 as necessary but insufficient: target, compiler, optional capability, cache access, and requested workflow need separate evidence.
• Treat an unknown version, failed required import, old Python, unavailable compiler for a compiled target, unreadable cache, invalid preference file, and unresolved optional native dependency as explicit unresolved limits.
• brian2.test() resets preferences while it runs and restores them afterward; use a narrow target/marker selection when diagnosing rather than launching the complete suite by default.

Bundled operating files

• installation.md: package identity, baseline dependencies, pip/Conda installation, compiler prerequisites, and optional capability boundaries.
• preferences-and-cache.md: preference access, file syntax and precedence, effective target/cache inspection, cache-clearing safeguards, and NFS/process guidance.
• troubleshooting.md: install/import, compiler/Cython, optional dependency, configuration/data, API, logging, and workflow triage with routing boundaries.
• check_brian2_env.py: non-mutating compact or JSON environment report. Use --help first; --strict gates required Python/package/import/version checks, and --require-compiler adds a compiler-name gate.

The script reports compiler names and capability states, not local paths, Python prefixes, or cache locations.