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 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

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

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.

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.

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.

Output files

OutputPath defines where OSS-DBSv2 writes results. In addition to numerical outputs, the software writes log files and status flags that are especially useful in automated or Lead-DBS-driven workflows.

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.