DirtyStatesHelper (in DirtyStatesHelper.py) maintains a dirtyParamCat value that records the deepest change made since the last successful run. EnumParamCats defines six levels in ascending depth:

On each Init & Run, SimMyelinatedAxon.preRun() reads dirtyParamCat and rebuilds only what has changed, avoiding redundant re-initialization of expensive structures such as RxD.

SimMyelinatedAxonCore.initRxDStaff() constructs a two-zone radial shell model around each axon trunk section:

• Inner zone (shells 1 … numShells): from axon membrane (R_a) to sheath boundary (R_sheath), diffusion coefficient D_k
• Outer zone (shells numShells+1 … total): from R_sheath to R_max, scaled diffusion D_k/α (myelinated) or D_k (node of Ranvier)

The transition between zones uses a harmonic mean of the two diffusion coefficients to avoid numerical discontinuities at the sheath boundary. All shell-to-shell transport is implemented as NEURON rxd.MultiCompartmentReaction with appropriate unit scaling (mM → molecules·μm⁻³).

Boundary conditions

• Node of Ranvier / unmyelinated sections: Dirichlet BC [K⁺] = ko0 at R_max, enforced explicitly on each timestep by ProcAdvanceHelper
• Myelinated sections (axonUnderSchwann): Zero-flux BC (RxD default) — no explicit action required

Flux injection

• Axon membrane K⁺ flux enters via segm._ref_kflux_i2fc into the innermost shell
• Schwann-cell flux is injected at the sheath-boundary shell (index numInnerShells−1), not the outermost shell, reflecting the physical position of the Schwann cell at R_sheath

A new ProcAdvanceHelper class (ProcAdvanceHelper.py) is called on every NEURON timestep via the UsesCustomProcAdvance mechanism. It performs three operations in order:

1. Enforce the Dirichlet BC at R_max for all non-myelinated segment outermost nodes
2. Clamp any negative concentration values to veryMinOuterConc (prevents NaN propagation)
3. Copy the sheath-boundary node concentration into schwann.ko for each Schwann-cell segment, so MOD files in Schwann sections can read the correct extracellular [K⁺]

The segment-to-node mapping for step 3 is pre-computed in the constructor (not per-timestep) for performance.

BaseAxonHelper.py encapsulates all logic for creating the base axon section before any myelination transformation. It handles:

• Predefined straight axon with user-specified L, diam, nseg
• Import from the currently loaded cell morphology (SWC / HOC)
• Hand-drawn mode with validation
• Fallback to predefined axon when import fails, with a user-visible warning

AxonTransformationHelper.py transforms the base axon into a biologically realistic myelinated structure. It creates:

• AISP / AISD sections (axon initial segment proximal / distal, 40 μm and 30 μm, respectively) at the soma junction
• Axon trunk — sections under each Schwann cell (axonUnderSchwann)
• Nodes of Ranvier between Schwann cells
• Insulator sections (1 nm diameter, 1 segment) as electrical spacers between morphological regions
• Schwann-cell sections with inner diameter = diam_sheath

Key data structures: AxonArcInterval (normalized 0–1 arc position) and Axon3DPointWithArc for 3D coordinate reconstruction.

CellBuildHelper.py provides a dockable panel for drawing axon sections by hand in Draw-by-hand mode. It validates the drawn topology and provides a warning footer when the geometry is invalid (e.g., the user clicks Init & Run before completing the drawing).

The simulation can record and display K⁺ concentration data in two modes, controlled by the isShowPyplotFigsInSubProcess flag:

In-process mode (PyplotAndSaveHelper)

Implemented in PyplotAndSaveHelper_Separated.py. Frames are stored directly in memory as OneFrame objects and rendered with matplotlib in the same process. A frame slider and start/stop button are provided for playback. Cumulative min/max tracking ensures consistent colour-scale across all frames.

Subprocess mode (PyplotSubProcHelper)

Implemented in PyplotSubProcHelper.py. Frames are serialised to .pickle files in a temporary folder (named frame0000.pickle, frame0001.pickle, …). A separate Python process reads and animates them via a polling timer, keeping the NEURON GUI responsive during long simulations. Marker files (running, save_to, saved) coordinate the lifecycle between producer and consumer.

Two visualisation types

• Colour map — 2D matrix of [K⁺] vs (shell index × segment index), rendered as a pcolormesh
• Per-shell curves — [K⁺] vs distance along the axon, one curve per radial shell

AnimSavePrintHelper.py is called from the simulation's custom procAdvance hook at intervals of Dt ms. On each frame it:

• Builds the concentration matrix from rxd.Species.nodes()
• Appends a new OneFrame to the recording
• Updates the seven optional NEURON graphs (ik vs dist, ko vs dist, voltage at 3 points, ek vs dist, v vs dist, per-Schwann ik and ko)
• Optionally prints segment-centre values every Dt ms

When the Save K⁺ conc(t, dist, radius) to TXT file checkbox is enabled, all recorded frames are written to a structured text file after the run completes. In subprocess mode, the save request is communicated via a marker file to avoid thread-safety issues; in in-process mode, PyplotAndSaveHelper.saveToTxtFile() is called directly.

PresentationParams.py consolidates all recording and display checkboxes into a single object used by both SimMyelinatedAxon and AnimSavePrintHelper:

• isAnim[0] — animate K⁺ radial colour map vs segment index
• isAnim[1] — animate K⁺ radial concentration vs distance per shell
• isSave — save to TXT (requires isAnim[1])
• isDraw[0..6] — seven individual NEURON graph enable/disable flags
• isPrint — console print of ik and ko at each Dt interval

Checking/unchecking isAnim automatically resets altRunControlWidget.isInited to prevent Continue from using stale RxD state.

AxonBiophysCompsHelper.py manages the MechManager interaction for the myelinated axon simulation. After the base axon geometry is established, it schedules a MechManager rescan (scheduleRescan(2)) and optionally shows the MechManager widget if the user has previously opened it. It also detects all un-insertable biophysics mechanism names from BrainCell's global list and skips them safely during biophysics application.

ProtoGeomStructs.py provides lightweight data classes used across the geometry pipeline to pass section properties (length, diameter, 3D point list, parent connectivity) between helpers without coupling them to specific NEURON section objects.

Exported multi-cell packages can be re-imported into BrainCell via _Testing/init_ImportExtraCells.hoc and the ExtraCellsManagerWidget. After re-import, the user can modify biophysics or connection parameters and perform a second export.

When scanning sections after re-import, extra-cell sections are identified by matching comp.name against the regular expression ^Extra Cell #(\d+)$. This is more robust than the previous approach of inspecting comp.list_ref[0].sec.name(), which was fragile after re-import because section names can change.

A new Geometry/Zoo/ folder provides reference morphologies for both cell types in plain format, independent of any nano-structure. These files are suitable for rapid prototyping, teaching, and validation workflows where nano-scale geometry is not required. Currently includes neuron_NEURON_HOC.hoc (48 kB) as a starting reference.

The import pipeline supports morphology files in three formats beyond plain HOC:

• SWC — standard morphology interchange format; processed via NLMorphologyConverter and cached in _Code/Import/temp_folder/last_converted.hoc
• ASC (Neurolucida) — converted via the same NLMorphologyConverter pathway
• ZIP archive — automatically unpacked; the first SWC file found inside is used

All three paths normalise to a temporary HOC file before loading, ensuring a single downstream import code path regardless of source format. The temporary file is regenerated only when the source changes, avoiding redundant conversion on repeated loads.

The following built-in simulations serve as reference implementations and templates for user-defined scenarios:

Each simulation's show() method must build its GUI using h.xpanel("") / h.xpanel() blocks as top-level containers. This ensures the simulation's controls appear inside SimManager's panel rather than as a detached pop-up window — a requirement enforced by SimManager's panel-embedding architecture. Using bc.VBox as the outermost container is explicitly disallowed for this reason.