dynamics

classes.dynamics

Attributes

Name	Description
REORDER_EQUATIONS
TEMPLATES
available_neural_mass_models

Classes

Name	Description
DynamicalSystem	Enhanced base class for `Dynamics` adding Python-side behaviour.
Dynamics	A named local neural-mass / population model: parameters, state variables, equations.
Model	Deprecated alias for `Dynamics`.

DynamicalSystem

classes.dynamics.DynamicalSystem(
    name='Dynamics',
    _skip_ontology=False,
    use_ontology=False,
    **kwargs,
)

Enhanced base class for Dynamics adding Python-side behaviour.

Wraps the generated LinkML Dynamics datamodel with the methods that make a model usable: ontology resolution (use_ontology=True), symbolic representation via SymPy, equation reordering, backend code generation, YAML / JSON / Pydantic round-tripping, and matplotlib plotting hooks.

Most users should construct via Dynamics or Dynamics.from_db(name) — this class is the implementation base.

Attributes

Name	Description
components	Alias for `modes` — sub-dynamics contained in this model.
symbolic	Full symbolic ODE system using proper SymPy conventions.

Methods

Name	Description
add_coupling_term	Deprecated. Use add_coupling_input() instead.
add_output	Add an output variable. Creates a derived_variable and adds its name to output list.
animate	Animate by sweeping one parameter through `values`.
copy	Return a deep copy of this experiment.
db_overview	Return a pandas DataFrame summarising the Dynamics database.
enrich_from_ontology	Explicitly enrich this model from the ontology by name.
from_datamodel	Create from a datamodel Dynamics instance by copying its
from_db	Load a Dynamics model by name from the tvbo database.
from_platform	Load a dynamics model from the tvbo platform API.
from_pydantic	Create a Dynamics from a tvbopydantic.Dynamics (or dict-like).
from_pyrates	Load a Dynamics model from a PyRates YAML template file.
get_symbolic_elements	Build a unified local_dict for parsing model expressions.
list_db	List available models in the tvbo database.
list_platform_models	List available dynamics models on the tvbo platform.
plot	Plot trajectories of this dynamics in 1D, 2D, or 3D.
render	Unified entry point for rendering the model in any output format.
render_equation_cse	Common-subexpression-eliminated variant of :meth:`render_equation`.
to_lems	Build a LEMS model for this local neural mass model.
to_pydantic	Return a tvbopydantic.Dynamics validated instance for this model.
to_yaml	Export the model to YAML format.
update_parameters_from_equations	Scan all equations and add any free symbols as parameters (default value if missing).

add_coupling_term

classes.dynamics.DynamicalSystem.add_coupling_term(
    name,
    description=None,
    unit=None,
)

Deprecated. Use add_coupling_input() instead.

add_output

classes.dynamics.DynamicalSystem.add_output(
    name,
    expression=None,
    *,
    unit=None,
    description=None,
)

Add an output variable. Creates a derived_variable and adds its name to output list.

animate

classes.dynamics.DynamicalSystem.animate(parameter, values, *dims, **kwargs)

Animate by sweeping one parameter through values.

See :func:tvbo.plot.dynamics.animate_dynamics for parameters. Returns a :class:matplotlib.animation.FuncAnimation.

copy

classes.dynamics.DynamicalSystem.copy(**overrides)

Return a deep copy of this experiment.

Use keyword overrides to set attributes on the returned copy.

Errors are not swallowed; if a field can’t be copied, an exception is raised.

db_overview

classes.dynamics.DynamicalSystem.db_overview(model_type=None)

Return a pandas DataFrame summarising the Dynamics database.

Columns: name, model_type, system_type, description.

Parameters

model_type : str, optional If given, only show models of that category.

Examples

Dynamics.db_overview() Dynamics.db_overview(model_type=‘neural_mass’)

enrich_from_ontology

classes.dynamics.DynamicalSystem.enrich_from_ontology()

Explicitly enrich this model from the ontology by name.

Looks up the model name in the TVB ontology and backfills missing parameter values, descriptions, ranges, state-variable metadata, and derived variables. Useful when you define a partial model spec and want the ontology to fill in the gaps.

Example

d = Dynamics.from_string(partial_spec) d.enrich_from_ontology() # fill in defaults from the knowledge base

from_datamodel

classes.dynamics.DynamicalSystem.from_datamodel(model_meta, use_ontology=False)

Create from a datamodel Dynamics instance by copying its already-normalized state (avoids _as_dict re-init crash on inlined_as_dict fields).

from_db

classes.dynamics.DynamicalSystem.from_db(name)

Load a Dynamics model by name from the tvbo database.

from_platform

classes.dynamics.DynamicalSystem.from_platform(name, base_url=TVBO_PLATFORM_URL)

Load a dynamics model from the tvbo platform API.

Fetches the full LinkML-valid YAML definition from the platform and constructs a Dynamics instance.

Parameters

name : str Model name (e.g., “JansenRit”, “ReducedWongWang”). base_url : str Platform base URL.

Returns

Dynamics Dynamics instance loaded from the platform.

from_pydantic

classes.dynamics.DynamicalSystem.from_pydantic(pyd_obj, use_ontology=False)

Create a Dynamics from a tvbopydantic.Dynamics (or dict-like).

from_pyrates

classes.dynamics.DynamicalSystem.from_pyrates(path, operator_key=None)

Load a Dynamics model from a PyRates YAML template file.

Parameters

path : str Path to PyRates YAML file. operator_key : str, optional Name of the specific OperatorTemplate to load (without _op suffix). If None, loads the first OperatorTemplate found. Use SimulationExperiment.from_pyrates() to load all operators.

Returns

Dynamics New Dynamics instance populated from the PyRates template.

Example

model = Dynamics.from_pyrates(“jansen_rit.yaml”) # Load specific operator from multi-operator file tsodyks = Dynamics.from_pyrates(“synaptic_plasticity.yaml”, operator_key=“tsodyks”)

get_symbolic_elements

classes.dynamics.DynamicalSystem.get_symbolic_elements(include_time_symbol=True)

Build a unified local_dict for parsing model expressions.

Includes symbols for parameters, coupling terms, derived parameters, derived variables, output transforms, state variables, function names, and (optionally) the time symbol ‘t’.

Returns

dict Mapping of names to SymPy objects suitable for parse_eq(local_dict=…).

list_db

classes.dynamics.DynamicalSystem.list_db(model_type=None)

List available models in the tvbo database.

Parameters

model_type : str, optional Filter by model category. Valid values: mean_field, neural_mass, phase_oscillator, phenomenological, spiking, generic, field.

Examples

Dynamics.list_db() # all models Dynamics.list_db(model_type=‘mean_field’) # mean-field only Dynamics.list_db(model_type=‘spiking’) # spiking models

list_platform_models

classes.dynamics.DynamicalSystem.list_platform_models(
    base_url=TVBO_PLATFORM_URL,
    **filters,
)

List available dynamics models on the tvbo platform.

Parameters

base_url : str Platform base URL. **filters Filtering parameters (e.g., system_type=“continuous”).

Returns

list[dict] List of model summaries.

plot

classes.dynamics.DynamicalSystem.plot(*dims, **kwargs)

Plot trajectories of this dynamics in 1D, 2D, or 3D.

See :func:tvbo.plot.dynamics.plot_dynamics for parameters.

render

classes.dynamics.DynamicalSystem.render(format='yaml', **kwargs)

Unified entry point for rendering the model in any output format.

Dispatches to the appropriate renderer based on format:

'yaml' — TVBO YAML specification
'pyrates-yaml' — PyRates YAML
'report' / 'markdown' / 'md' — human-readable Markdown report
'pdf' — report rendered to PDF (requires outputfile kwarg)
'neuroml' / 'nml' / 'lems' — LEMS XML via NeuroMLAdapter
Any code format accepted by :meth:render_code ('tvb', 'jax', 'julia', 'bifurcation-julia', …)

Parameters

format : str Target output format. **kwargs Forwarded to the underlying renderer.

Returns

str

render_equation_cse

classes.dynamics.DynamicalSystem.render_equation_cse(
    obj,
    format='numpy',
    inline_functions=False,
    **kwargs,
)

Common-subexpression-eliminated variant of :meth:render_equation.

Returns (setup, final) — a list of (name, expr) assignments plus the return expression — so interpreted backends (TVB / numpy) evaluate each shared subexpression (notably repeated model-function calls) once instead of per occurrence. Builds the same symbolic scope / user-function set as :meth:render_equation; see :func:tvbo.codegen.code.render_equation_cse.

to_lems

classes.dynamics.DynamicalSystem.to_lems(
    initial_conditions=1,
    component_id=None,
)

Build a LEMS model for this local neural mass model.

.. deprecated:: Use NeuroMLAdapter(model).render_code() from tvbo.adapters.neuroml instead. This method returns a lems.Model object (PyLEMS API); the adapter produces a validated XML string.

Parameters: - initial_conditions: number or dict; if number, used for all SVs; if dict, keys are sv name or sv_name_0 - component_id: optional id for the component; defaults to model label

Returns: - lems.Model instance containing a ComponentType and a Component for this model

to_pydantic

classes.dynamics.DynamicalSystem.to_pydantic()

Return a tvbopydantic.Dynamics validated instance for this model.

to_yaml

classes.dynamics.DynamicalSystem.to_yaml(filepath=None, format='tvbo')

Export the model to YAML format.

Parameters

filepath : str, optional Path to write the YAML file. If None, returns the YAML string. format : str Output format: “tvbo” (default) or “pyrates”. PyRates format generates a complete experiment YAML (model + network).

Returns

str YAML string or filepath if written to file.

Example

model.to_yaml(“model.yaml”) # TVBO format model.to_yaml(“model.yaml”, format=“pyrates”) # PyRates experiment format

update_parameters_from_equations

classes.dynamics.DynamicalSystem.update_parameters_from_equations(
    default_value=1.0,
    overwrite=False,
)

Scan all equations and add any free symbols as parameters (default value if missing).

Skips symbols that are known state variables, derived variables, or function arguments
Skips the time symbol ‘t’
Removes any previously added parameters that later become known entities
Returns the list of parameter names that were added (or updated if overwrite=True)

Dynamics

classes.dynamics.Dynamics(name=None, **kwargs)

A named local neural-mass / population model: parameters, state variables, equations.

The smallest runnable unit in TVBO. A Dynamics binds a name to a set of parameters and an ODE system, and is round-trippable through YAML, SymPy, and any of the supported backends (JAX, TVB, PyRates, Julia, …).

Construct one inline, from the curated TVB-O database, or by IRI:

Examples

from tvbo import Dynamics

# Inline
lorenz = Dynamics(
    parameters={"sigma": {"value": 10.0}, "rho": {"value": 28.0},
                "beta": {"value": 8/3}},
    state_variables={
        "X": {"equation": {"rhs": "sigma * (Y - X)"}},
        "Y": {"equation": {"rhs": "X * (rho - Z) - Y"}},
        "Z": {"equation": {"rhs": "X * Y - beta * Z"}},
    },
)

# From the curated database
rww = Dynamics.from_db("ReducedWongWangExcInh")

# By IRI (resolved at construction time)
rww = Dynamics(iri="tvbo:ReducedWongWangExcInh")

See the writing-models skill for the YAML form and equation conventions.

Model

classes.dynamics.Model(name, ontology=None, metadata=None, **kwargs)

Deprecated alias for Dynamics.

Kept for backwards compatibility — new code should use Dynamics.

Functions

Name	Description
class2metadata	Populate a `Dynamics` metadata object from an owlready2 ontology class.
clean_code	Replace Unicode infinity (`∞`) with the Python literal `inf`.
order_by_equations	Orders the `derived_variables` dictionary based on the key order of the `dependent_equations` dictionary.
sort_equations	Reorder `model[variable_type]` by topological dependency order, in place.
update_equations	Normalize equation symbols on model (in place).
update_parameters	Update parameters from ontology.

class2metadata

classes.dynamics.class2metadata(ontoclass, metadata)

Populate a Dynamics metadata object from an owlready2 ontology class.

Fills in description, state variables (with equations, boundaries, and coupling-variable flags), derived variables, and parameters by querying the TVB-O ontology for the corresponding semantic annotations.

Parameters

Name	Type	Description	Default
ontoclass	Any	The owlready2 class to read from.	required
metadata	Any	The `Dynamics` instance to populate in place.	required

clean_code

classes.dynamics.clean_code(code)

Replace Unicode infinity (∞) with the Python literal inf.

Generated model code occasionally carries the ∞ glyph from upstream ontology labels; SymPy and most backends can’t parse it.

order_by_equations

classes.dynamics.order_by_equations(derived_variables, dependent_equations)

Orders the derived_variables dictionary based on the key order of the dependent_equations dictionary.

Parameters: derived_variables (dict): Dictionary to be ordered. dependent_equations (dict): Dictionary providing the key order for sorting.

Returns: dict: A new dictionary ordered by the key order from dependent_equations.

sort_equations

classes.dynamics.sort_equations(model, variable_type)

Reorder model[variable_type] by topological dependency order, in place.

Resolves the model’s equation dependency DAG and reorders the variables so each equation appears after the variables it references — required by backends that emit straight-line code (JAX, NumPy printers).

Parameters

Name	Type	Description	Default
model	Any	The dynamics model whose equations should be sorted.	required
variable_type	str	Attribute name — typically `"state_variables"`, `"derived_variables"`, or `"functions"`.	required

update_equations

classes.dynamics.update_equations(model)

Normalize equation symbols on model (in place).

Builds a substitution map that rewrites raw RHS strings into canonical SymPy form: *_dot / dot* names become time derivatives, derived variables are inlined, and Heaviside / acronym placeholders are resolved.

update_parameters

classes.dynamics.update_parameters(
    metadata,
    ontoclass,
    verbose=0,
    only_used=True,
    **kwargs,
)

Update parameters from ontology.

Parameters

metadata : Dynamics Model metadata to update ontoclass : owlready2.ThingClass Ontology class verbose : int Verbosity level only_used : bool If True (default), only add parameters that are referenced in equations. If False, add all parameters from ontology (legacy behavior). **kwargs : dict Parameter overrides