utils
templates.tvboptim.utils
TVB-Optim Template Utilities
Reusable Python functions for tvboptim Mako templates. Import these in template blocks to avoid code duplication.
Usage in templates
<% from tvbo.templates.tvboptim.utils import ( safe_name, as_list, is_network_observation, parse_loss_function, get_observation_refs ) %>
Functions
| Name | Description |
|---|---|
| as_list | Convert dict or list to list of values. |
| format_bounds_array | Render a list of SymPy bound values as a code-level list literal. |
| get_all_hyperparams | Get all hyperparameters including from included algorithms. |
| get_all_observations_from_algo | Get all observation names including from included algorithms. |
| get_attr | Safe attribute access. |
| get_domain_bounds | Lookup domain bounds from model.parameters or coupling.parameters. |
| get_include_info | Extract algorithm name and argument overrides from AlgorithmInclude. |
| get_node_param_overrides | Scan network.nodes for per-node parameter overrides. |
| get_node_state_overrides | Scan network.nodes for per-node initial state overrides. |
| get_observation_refs | Categorize observations into network vs simulation-derived. |
| get_param_info | Extract parameter names, defaults, and shapes from a parameters collection. |
| get_state_bounds | Extract state variable bounds as SymPy expressions. |
| is_external_observation | Check if observation is external (has data_source or network.observations source). |
| is_network_observation | Check if observation is a network observation (static data from BIDS). |
| obs_has_all_args | Check if observation has all required arguments satisfied. |
| parse_exploration | Parse exploration specification from YAML. |
| parse_free_param | Parse a free_parameter entry. |
| parse_loss_arguments | Parse loss function call arguments. |
| parse_loss_function | Parse optimization loss function specification. |
| safe_name | Convert name to valid Python identifier. |
| to_numeric | Convert string to numeric if possible. |
as_list
templates.tvboptim.utils.as_list(obj)Convert dict or list to list of values.
format_bounds_array
templates.tvboptim.utils.format_bounds_array(bounds, format='jax')Render a list of SymPy bound values as a code-level list literal.
Uses the appropriate TVBO code printer so infinity is rendered correctly for any backend (jnp.inf, np.inf, Inf, …).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| bounds | List | list of sympy expressions (Float / oo / -oo) | required |
| format | str | target backend ('jax', 'numpy', 'julia', …) |
'jax' |
Returns
| Name | Type | Description |
|---|---|---|
| str | String like [-10.0, -jnp.inf] ready for code generation. |
get_all_hyperparams
templates.tvboptim.utils.get_all_hyperparams(algo, algorithms_dict)Get all hyperparameters including from included algorithms.
get_all_observations_from_algo
templates.tvboptim.utils.get_all_observations_from_algo(algo, algorithms_dict)Get all observation names including from included algorithms.
get_attr
templates.tvboptim.utils.get_attr(obj, name, default=None)Safe attribute access.
get_domain_bounds
templates.tvboptim.utils.get_domain_bounds(param_name, model, all_couplings)Lookup domain bounds from model.parameters or coupling.parameters.
Returns (lo, hi) tuple, where None means unbounded.
get_include_info
templates.tvboptim.utils.get_include_info(inc)Extract algorithm name and argument overrides from AlgorithmInclude.
Returns (algo_name, {param_name: value}) tuple.
get_node_param_overrides
templates.tvboptim.utils.get_node_param_overrides(
network,
n_nodes,
dyn_param_defaults,
)Scan network.nodes for per-node parameter overrides.
When nodes define parameters that differ from the dynamics defaults, build per-node arrays. Only parameters that differ on at least one node are returned.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | Any | Network object with .nodes list | required |
| n_nodes | int | number of nodes | required |
| dyn_param_defaults | Dict[str, float] | dict of param_name -> scalar default from dynamics | required |
Returns
| Name | Type | Description |
|---|---|---|
| Dict[str, List[float]] | dict of param_name -> list of per-node values (length n_nodes) |
get_node_state_overrides
templates.tvboptim.utils.get_node_state_overrides(
network,
n_nodes,
state_names,
default_initial_state,
)Scan network.nodes for per-node initial state overrides.
When nodes define state: {theta: {value: 0.8}} in the YAML, build per-node arrays for state variables that differ across nodes.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | Any | Network object with .nodes list | required |
| n_nodes | int | number of nodes | required |
| state_names | List[str] | ordered list of state variable names | required |
| default_initial_state | List[float] | default initial value per state variable | required |
Returns
| Name | Type | Description |
|---|---|---|
| Dict[str, List[float]] | dict of sv_name -> list of per-node values (length n_nodes) |
get_observation_refs
templates.tvboptim.utils.get_observation_refs(observations_dict)Categorize observations into network vs simulation-derived.
Returns
| Name | Type | Description |
|---|---|---|
| Tuple[Set[str], List[str]] | (network_observation_names, observation_names_with_all_args) |
get_param_info
templates.tvboptim.utils.get_param_info(parameters)Extract parameter names, defaults, and shapes from a parameters collection.
Works for both model.parameters and coupling.parameters.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| parameters | dict | dict-like of Parameter objects | required |
Returns
| Name | Type | Description |
|---|---|---|
| tuple | Tuple[List[str], Dict[str, float], Dict[str, str]] | (param_names, param_defaults, param_shapes) - param_names: list of parameter names - param_defaults: dict of name -> scalar value (for DEFAULT_PARAMS) - param_shapes: dict of name -> shape string (only for params with shape attribute) |
get_state_bounds
templates.tvboptim.utils.get_state_bounds(model)Extract state variable bounds as SymPy expressions.
Uses sympy.oo for unbounded dimensions so that code printers automatically render the correct backend literal (jnp.inf, np.inf, Inf, etc.).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| model | Any | Dynamics instance with .state_variables |
required |
Returns
| Name | Type | Description |
|---|---|---|
| tuple | Tuple[List, List, bool] | (bounds_lo, bounds_hi, has_finite_bounds) - bounds_lo: list of sympy expressions (Float or -oo) - bounds_hi: list of sympy expressions (Float or oo) - has_finite_bounds: True if any bound is finite |
is_external_observation
templates.tvboptim.utils.is_external_observation(obs)Check if observation is external (has data_source or network.observations source).
is_network_observation
templates.tvboptim.utils.is_network_observation(obs)Check if observation is a network observation (static data from BIDS).
Network observations have source starting with ‘network.observations’.
obs_has_all_args
templates.tvboptim.utils.obs_has_all_args(obs)Check if observation has all required arguments satisfied.
Returns True if all pipeline step arguments either have values or are implicitly satisfied by source.
parse_exploration
templates.tvboptim.utils.parse_exploration(
expl,
all_couplings,
get_pipeline_output_key_fn=None,
)Parse exploration specification from YAML.
Returns dict with: name, label, mode, n_parallel, axes, observable_*
parse_free_param
templates.tvboptim.utils.parse_free_param(
fp,
coupling_keys,
model=None,
all_couplings=None,
)Parse a free_parameter entry.
Handles: str, dotted notation, stringified dict, dict, and Parameter objects.
name, heterogeneous, shape, coupling_key, dynamics_key,
lower_bound, upper_bound
parse_loss_arguments
templates.tvboptim.utils.parse_loss_arguments(loss_call)Parse loss function call arguments.
Returns
| Name | Type | Description |
|---|---|---|
| List[Dict] | (parsed_args, obs_refs) where: | |
| Set[str] | - parsed_args: list of dicts with ‘name’, ‘type’, and type-specific keys | |
| Tuple[List[Dict], Set[str]] | - obs_refs: set of observation names referenced |
parse_loss_function
templates.tvboptim.utils.parse_loss_function(opt)Parse optimization loss function specification.
Returns dict with: opt_name, func_name, args, obs_refs, agg_over, agg_type or None if no loss defined.
safe_name
templates.tvboptim.utils.safe_name(name)Convert name to valid Python identifier.
to_numeric
templates.tvboptim.utils.to_numeric(val)Convert string to numeric if possible.