Input and Settings Reference ============================ OSS-DBSv2 simulations are configured through a JSON input file. This page gives an overview of the most important top-level sections so external users can map their modeling question to the required settings. For a runnable minimal example, see `input_files/inputTest.json `_. Use that file together with :doc:`tutorial` if you want to compare the reference explanations here with a working end-to-end example. Top-level structure ------------------- The most common sections are: - ``BrainRegion``: size, shape, and position of the simulated brain domain - ``Electrodes``: electrode models, orientation, contact activation, and encapsulation layer settings - ``MaterialDistribution``: MRI and optional DTI inputs plus tissue label mapping - ``DielectricModel``: electrical material model used for each tissue class - ``Mesh``: mesh generation and mesh-size controls - ``StimulationSignal``: current- or voltage-controlled excitation settings - ``Solver``: linear solver and preconditioner configuration - ``PointModel``: lattice- or pathway-based post-processing - ``OutputPath``: destination for logs and generated result files Not every workflow needs every section. A first standalone run usually depends most on ``BrainRegion``, ``Electrodes``, ``MaterialDistribution``, ``StimulationSignal``, and ``OutputPath``. Brain region ------------ ``BrainRegion`` defines the simulation domain around the electrode. A typical section contains: - ``Center``: the center of the domain in millimeters - ``Dimension``: the extent in x, y, and z direction - ``Shape``: for example ``Sphere`` or another supported geometry type like ``Box`` or ``Ellipsoid`` For standalone usage, this is often the first section to adapt when moving from an example dataset to a new subject or experiment. Electrodes ---------- ``Electrodes`` is a list. Each entry describes one implanted electrode with: - ``Name``: the electrode model to instantiate - ``TipPosition``: electrode tip location in millimeters - ``Direction``: implantation axis - ``Rotation[Degrees]``: rotation around the electrode axis - ``Contacts``: activity and boundary conditions for each contact - ``EncapsulationLayer``: optional peri-electrode layer properties Each contact can specify whether it is active, floating, current-controlled, or voltage-controlled. Contact-level mesh settings can also be added when local refinement is needed. Material distribution --------------------- ``MaterialDistribution`` connects imaging data to tissue classes: - ``MRIPath`` points to a segmented MRI volume - ``MRIMapping`` translates integer labels in the MRI to OSS-DBSv2 tissue names - ``DiffusionTensorActive`` enables anisotropy from DTI data - ``DTIPath`` points to the diffusion tensor image when used This section is central for subject-specific modeling. If ``DiffusionTensorActive`` is ``false``, the simulation uses the scalar tissue properties only. Dielectric model ---------------- ``DielectricModel`` selects how tissue conductivity and permittivity are modeled. The code currently exposes models such as ``ColeCole4``, ``ColeCole3``, and ``Constant``. Typical usage: - use a Cole-Cole model for frequency-dependent tissue properties - use the constant model when a homogeneous or fixed-conductivity setup is needed - provide ``CustomParameters`` when deviating from the built-in defaults Mesh and solver --------------- ``Mesh`` and ``Solver`` control numerical performance and accuracy. Important mesh settings include: - ``LoadMesh`` / ``SaveMesh`` for mesh reuse - ``MeshElementOrder`` for the geometric discretization - ``MeshingHypothesis`` for coarse-to-fine global mesh sizing - ``MeshSize`` for targeted local refinement - ``HPRefinement`` for combined geometric and polynomial refinement near boundaries See :ref:`mesh-refinement` for a full description of all mesh control options. Important solver settings include: - ``Type`` such as ``CG``, ``GMRES``, or ``Direct`` - ``Preconditioner`` such as ``bddc`` or ``local`` - ``MaximumSteps`` and ``Precision`` For most new users, the example defaults are a good starting point. Solver and mesh tuning usually becomes important only for large studies or demanding anisotropic models. See :ref:`solver-guidance` for detailed recommendations on solver and preconditioner selection. Stimulation signal ------------------ ``StimulationSignal`` defines how the excitation is represented. Common fields include: - ``CurrentControlled`` to switch between current- and voltage-controlled setups - ``Type`` for the signal class - frequency or pulse-shape parameters depending on the chosen model Different workflows use different subsets of these settings. When importing from Lead-DBS, several values are generated automatically. See :ref:`stimulation-modes` for a detailed description of how current- and voltage-controlled stimulation interact with contact configurations. Point models and post-processing -------------------------------- ``PointModel`` controls field evaluation away from the FEM mesh: - ``Lattice`` evaluates the field on a regular grid and can be used for VTA-like analyses - ``Pathway`` activates pathway-based analysis when tract data are available These options are often disabled for a first validation run and enabled later once the core volume conductor setup is working as expected. Surfaces -------- The optional ``Surfaces`` block sets boundary conditions on the outer brain surface. This is primarily used to treat the brain boundary as a grounded electrode in monopolar stimulation setups: .. code-block:: json "Surfaces": [ { "Name": "BrainSurface", "Active": true, "Voltage[V]": 0.0, "Floating": false } ] Each entry uses the same fields as a contact definition (``Active``, ``Voltage[V]``, ``Floating``, ``Current[A]``). The ``Name`` must match a boundary name in the geometry — the default outer boundary is called ``BrainSurface``. If ``Surfaces`` is omitted or empty, the outer boundary is left as a natural (zero-flux) boundary condition. .. _stimsets-workflow: StimSets (batch stimulation) ---------------------------- The ``StimSets`` workflow enables efficient batch simulation of many stimulation protocols on the same electrode geometry. Instead of running a full mesh-generation and FEM solve for every protocol, StimSets exploits linearity: it computes one **unit solution** per contact and then superimposes them with protocol-specific scaling factors. JSON configuration ^^^^^^^^^^^^^^^^^^ .. code-block:: json "StimSets": { "Active": true, "StimSetsFile": "Current_protocol.csv" } - ``Active`` (default: ``false``) — enable the StimSets workflow. - ``StimSetsFile`` — path to a CSV file containing stimulation protocols (see format below). Can also be ``null`` when using the Python API with a ``CurrentVector`` instead. Requirements ^^^^^^^^^^^^ - Stimulation must be **current-controlled** (``CurrentControlled: true``). - Exactly one contact or surface must serve as **ground** with ``Current[A]: -1``. This is typically the brain surface (``Surfaces`` block) or one active electrode contact. - The preconditioner is automatically set to ``local`` (floating contacts require it). CSV format ^^^^^^^^^^ The CSV file has a header row with contact names and one row per stimulation protocol. Values are in **milliamps** (the code converts to Amperes by multiplying by 1e-3). NaN values are treated as zero current. .. code-block:: text Contact0,Contact1,Contact2,Contact3 -1.954,0.0,-0.983,0.0 -3.811,-0.933,-2.437,0.784 The number of columns must match the number of non-ground contacts. Execution workflow ^^^^^^^^^^^^^^^^^^ The StimSets pipeline proceeds in two stages: **Stage 1 — Unit solutions** (``ossdbs``): 1. A single mesh is generated and h-refined (material bisection), then saved to disk. 2. For each non-ground contact, the mesh is reloaded, HP refinement is re-applied, and a unit-current FEM solve is performed (1 A on that contact, all others floating, ground at −1 A). 3. Unit solutions are stored in per-contact directories named ``E1C1``, ``E1C2``, etc. **Stage 2 — Pathway activation** (``run_pathway_activation``): 1. All unit solutions are loaded from the per-contact directories. 2. For each row in the CSV file, the unit solutions are scaled by the protocol currents and superimposed. 3. The resulting time-domain field is passed to the NEURON model for axon activation analysis. Stage 2 is run separately after stage 1: .. code-block:: bash run_pathway_activation input.json This separation allows re-running the PAM stage with different protocol files or scaling factors without repeating the expensive FEM solves. Additional top-level settings ----------------------------- Several top-level keys control the FEM formulation and output behaviour: - ``EQSMode`` (default: ``false``) — enable electro-quasi-static mode. When ``true``, the FEM solve uses complex-valued spaces to account for capacitive tissue effects at non-zero frequencies. When ``false``, only real conductivity is used (quasi-static approximation). - ``FEMOrder`` (default: 2) — polynomial order of the finite-element space. Higher orders improve accuracy at the cost of more degrees of freedom. This is independent of ``MeshElementOrder``, which controls the geometric mesh curvature. - ``ComputeImpedance`` (default: ``false``) — compute the complex impedance at each frequency and write ``impedance.csv``. - ``ComputeCurrents`` (default: ``false``) — estimate contact currents at each frequency by integrating the normal current density over contact surfaces. - ``ExportVTK`` (default: ``false``) — export potential, E-field, conductivity, and material distributions as VTU files for ParaView. - ``ExportElectrode`` (default: ``false``) — export electrode geometry as VTU and Netgen mesh files. - ``ExportFrequency`` (default: ``null``) — frequency at which VTK export is performed. If ``null``, the median frequency is used. Output files ------------ ``OutputPath`` defines where OSS-DBSv2 writes results. The following files may be produced depending on the configuration: **Always written:** - ``ossdbs.log`` — full log of the simulation run - ``VCM_report.json`` — degrees of freedom, element count, and solver timings **Controlled by JSON flags:** - ``ComputeImpedance: true`` produces ``impedance.csv`` with columns ``freq``, ``real``, ``imag``. For current-controlled multicontact setups, ``admittance_matrix.csv`` and ``impedance_matrix.csv`` are also written (flat format: ``freq``, ``row``, ``col``, ``real``, ``imag``). - ``ExportVTK: true`` produces VTU files for ParaView visualisation: ``potential.vtu``, ``E-field.vtu``, ``conductivity.vtu``, and ``material.vtu``. - ``ExportElectrode: true`` produces ``electrode_N.vtu`` and ``electrode_N.vol.gz`` for each electrode. **Produced by specific workflows:** - **Floating contacts**: ``floating_potentials.csv`` (frequency-domain floating voltages) and ``floating_in_time.csv`` (reconstructed time-domain values). - **Time-domain signal**: ``stimulation_in_time.csv`` (reconstructed stimulation waveform at contact surfaces) and ``time_domain_signal.pdf`` (plot of the reconstructed signal). - **Point model (Lattice)**: ``oss_lattice_*.h5`` with potential and field values on the evaluation grid. - **Point model (Pathway)**: ``oss_pathway_*.h5`` with field values sampled along axon trajectories, plus activation results when NEURON is available. - **VTA**: ``oss_vta.nii`` (NIfTI volume of tissue activated). - ``SaveMesh: true``: ``mesh.vol.gz`` for later reuse. When adapting examples, it is often helpful to choose an explicit output folder per subject or experiment so results from different runs do not get mixed. Practical advice ---------------- - Start from a working example instead of writing a JSON file from scratch. - Change one section at a time when adapting to a new dataset. - Keep paths explicit when running batch jobs or working outside the example directories. - Validate the electrode definition and MRI label mapping early, since these settings strongly influence downstream results. Related pages ------------- - :doc:`tutorial` - :doc:`lead_dbs` - :doc:`examples` - :doc:`brain_geometry` - :doc:`materials` - :doc:`stimulation_signals` - :doc:`volume_conductor_model`