`cubnm.sim`¶

Simulation of the models

`SimGroup`	Group of simulations that are executed in parallel
`rWWSimGroup`	Group of reduced Wong-Wang simulations (Deco 2014)
`rWWExSimGroup`	Group of reduced Wong-Wang simulations (excitatory only, Deco 2013)
`KuramotoSimGroup`	Group of Kuramoto simulations that are executed in parallel
`MultiSimGroupMixin`	Mixin for combining multiple simulation groups into one,

create_multi_sim_group(sim_group_cls)

Dynamically creates a MultiSimGroup class by combining

class cubnm.sim.SimGroup(duration, TR, sc, sc_dist=None, out_dir=None, dt='0.1', bw_dt='1.0', ext_out=True, states_ts=False, states_sampling=None, noise_out=False, do_fc=True, do_fcd=True, window_size=10, window_step=2, rand_seed=410, exc_interhemispheric=False, force_cpu=False, force_gpu=False, serial_nodes=False, gof_terms=['+fc_corr', '-fcd_ks'], bw_params='friston2003', bold_remove_s=30, fcd_drop_edges=True, noise_segment_length=30, sim_verbose=False, progress_interval=500)¶

Group of simulations that are executed in parallel (as possible depending on the available hardware) on GPU/CPU.

Parameters¶

duration: float

simulation duration (in seconds)

TR: float

BOLD TR (in seconds)

sc: str or np.ndarray

path to structural connectome strengths (as an unlabled .txt) or a numpy array Shape: (nodes, nodes) If asymmetric, rows are sources and columns are targets.

sc_dist: str or np.ndarray, optional

path to structural connectome distances (as an unlabled .txt) or a numpy array Shape: (nodes, nodes) If provided v (velocity) will be a free parameter and there will be delay in inter-regional connections If asymmetric, rows are sources and columns are targets.

out_dir: {str or ‘same’ or None}, optional

str: will create a directory in the provided path
‘same’: will create a directory named based on sc
(only should be used when sc is a path and not a numpy array)
None: will not have an output directory (and cannot save outputs)

dt: decimal.Decimal or str, optional

model integration time step (in msec)

bw_dt: decimal.Decimal or str, optional

Ballon-Windkessel integration time step (in msec)

ext_out: bool, optional

return model state variables to self.sim_states

states_ts: bool, optional

return time series of model states to self.sim_states Note that this will increase the memory usage and is not recommended for large number of simulations (e.g. in a grid search)

states_sampling: float, optional

sampling rate of model states in seconds. Default is None, which uses BOLD TR as the sampling rate.

noise_out: bool, optional

return noise time series

do_fc: bool, optional

calculate simulated functional connectivity (FC)

do_fcd: bool, optional

calculate simulated functional connectivity dynamics (FCD)

window_size: int, optional

dynamic FC window size (in TR) Must be even. The actual window size is +1 (including center)

window_step: int, optional

dynamic FC window step (in TR)

rand_seed: int, optional

seed used for the noise simulation

exc_interhemispheric: bool, optional

excluded interhemispheric connections from sim FC and FCD calculations

force_cpu: bool, optional

use CPU for the simulations (even if GPU is available). If set to False the program might use GPU or CPU depending on GPU availability

force_gpu: bool, optional

on some HPC/HTC systems occasionally GPUtil might not detect an available GPU device. Use this if there is a GPU available but is not being used for the simulation. If set to True but a GPU is not available will lead to errors.

serial_nodes: bool, optional

only applicable to GPUs; uses one thread per simulation and do calculation of nodes serially. This is an experimental feature which is generally not recommended and has significantly slower performance in typical use cases. Only may provide performance benefits with very large grids as computing time does not scale with the number of simulations as much as the parallel (default) mode.

gof_terms: list of str, optional

list of goodness-of-fit terms to be used for scoring. May include: - ‘-fcd_ks’: negative Kolmogorov-Smirnov distance of FCDs - ‘+fc_corr’: Pearson correlation of FCs - ‘-fc_diff’: negative absolute difference of FC means - ‘-fc_normec’: negative Euclidean distance of FCs divided by max EC [sqrt(n_pairs*4)]

bw_params: {‘friston2003’ or ‘heinzle2016-3T’ or dict}, optional

see cubnm.utils.get_bw_params() for details

bold_remove_s: float, optional

remove the first bold_remove_s seconds from the simulated BOLD in FC, FCD and mean state calculations (but the entire BOLD will be returned to .sim_bold)

fcd_drop_edges: bool, optional

drop the edge windows in FCD calculations

noise_segment_length: float or None, optional

in seconds, length of the noise segments in the simulations The noise segment will be repeated after shuffling of nodes and time points. To generate noise for the entire simulation without repetition, set this to None. Note that varying the noise segment length will result in a different noise array even if seed is fixed (but fixed combination of seed and noise_segment_length will result in reproducible noise)

sim_verbose: bool, optional

verbose output of the simulation including details of simulations and a progress bar. This may slightly make the simulations slower.

progress_interval: int, optional

msec; interval of progress updates in the simulation Only used if sim_verbose is True

Attributes¶

param_lists: dict of np.ndarray

dictionary of parameter lists, including

global parameters with shape (N_SIMS,)
regional parameters with shape (N_SIMS, nodes)
‘v’: conduction velocity. Shape: (N_SIMS,)

Additional attributes will be added after running the simulations. See cubnm.sim.SimGroup._process_out() for details.

Notes¶

Derived classes must set the following attributes:

model_name: str: name of the model used in the simulations
global_param_names: list of str: names of global parameters
regional_param_names: list of str: names of regional parameters
state_names: list of str: names of the state variables
sel_state_var: str: name of the state variable used in the tests
n_noise: int: number of noise elements per node per time point (e.g. 2 if there are noise to E and I neuronal populations)

And they must implement the following methods:

_set_default_params: set default (example) parameters for the simulations

get_config(include_N=False, for_reinit=False)¶

Get the configuration of the simulation group

Parameters¶

include_N: bool, optional: include N in the output config is ignored when for_reinit is True
for_reinit: bool, optional: include the parameters that need reinitialization of the simulation core session if changed

Returns¶

config: dict: dictionary of simulation group configuration

run(force_reinit=False)¶

Run the simulations in parallel (as possible) on GPU/CPU through the cubnm._core.run_simulations() function which runs compiled C++/CUDA code.

Parameters¶

force_reinit: bool, optional: force reinitialization of the session. At the beginning of each session (when cubnm is imported) some variables are initialized on CPU/GPU and reused in every run. Set this to True if you want to reinitialize these variables. This is rarely needed.

get_noise()¶

Get the (recreated) noise time series. This requires recreation of the noise array if noise segmenting is on. Noise will be recreated based on shuffling indices of nodes and time steps, similar to how it is done in the core code.

Returns¶

noise: np.ndarray: Noise segment array. Shape: (n_noise, nodes, time_steps, 10)

clear()¶: Clear the simulation outputs

score(emp_fc_tril=None, emp_fcd_tril=None, emp_bold=None)¶

Calcualates individual goodness-of-fit terms and aggregates them.

Parameters¶

emp_fc_tril: np.ndarray or None: 1D array of empirical FC lower triangle. Shape: (edges,)
emp_fcd_tril: np.ndarray or None: 1D array of empirical FCD lower triangle. Shape: (window_pairs,)
emp_bold: np.ndarray or None: cleaned and parcellated empirical BOLD time series. Shape: (nodes, volumes) Motion outliers should either be excluded (not recommended as it disrupts the temporal structure) or replaced with zeros. If provided emp_fc_tril and emp_fcd_tril will be ignored.

Returns¶

scores: pd.DataFrame: The goodness of fit measures (columns) of each simulation (rows)

save(save_as='npz')¶

Save simulation outputs to disk.

Parameters¶

save_as: {‘npz’ or ‘txt’}, optional

‘npz’: all the output of all sims will be written to a npz file
‘txt’: outputs of simulations will be written to separate files, recommended when N = 1 (e.g. rerunning the best simulation)

class cubnm.sim.rWWSimGroup(*args, do_fic=True, max_fic_trials=0, fic_penalty=True, fic_i_sampling_start=1000, fic_i_sampling_end=10000, fic_init_delta=0.02, **kwargs)¶

Bases: SimGroup

Group of reduced Wong-Wang simulations (Deco 2014) that are executed in parallel

Parameters¶

do_fic: bool, optional: do analytical (Demirtas 2019) & numerical (Deco 2014) Feedback Inhibition Control. If provided wIE parameters will be ignored
max_fic_trials: int, optional: maximum number of trials for FIC numerical adjustment. If set to 0, FIC will be done only analytically
fic_penalty: bool, optional: penalize deviation from FIC target mean rE of 3 Hz
fic_i_sampling_start: int, optional: starting time of numerical FIC I_E sampling (msec)
fic_i_sampling_end: int, optional: end time of numerical FIC I_E sampling (msec)

fic_init_delta: float, optional *args, **kwargs:

see cubnm.sim.SimGroup for details

Attributes¶

param_lists: dict of np.ndarray

dictionary of parameter lists, including

‘G’: global coupling. Shape: (N_SIMS,)
‘wEE’: local excitatory self-connection strength. Shape: (N_SIMS, nodes)
‘wEI’: local inhibitory self-connection strength. Shape: (N_SIMS, nodes)
‘wIE’: local excitatory to inhibitory connection strength. Shape: (N_SIMS, nodes)
‘v’: conduction velocity. Shape: (N_SIMS,)

Example¶

To see example usage in grid search and evolutionary algorithms see cubnm.optimize.

Here, as an example on how to use SimGroup independently, we will run a single simulation and save the outputs to disk.

from cubnm import sim, datasets

sim_group = sim.rWWSimGroup(
    duration=60,
    TR=1,
    sc=datasets.load_sc('strength', 'schaefer-100'),
)
sim_group.N = 1
sim_group.param_lists['G'] = np.repeat(0.5, N_SIMS)
sim_group.param_lists['wEE'] = np.full((N_SIMS, nodes), 0.21)
sim_group.param_lists['wEI'] = np.full((N_SIMS, nodes), 0.15)
sim_group.run()

model_name = 'rWW'¶

global_param_names = ['G']¶

regional_param_names = ['wEE', 'wEI', 'wIE']¶

state_names = ['I_E', 'I_I', 'r_E', 'r_I', 'S_E', 'S_I']¶

sel_state_var = 'r_E'¶

n_noise = 2¶

get_config(*args, **kwargs)¶

Get the configuration of the simulation group

Parameters¶

include_N: bool, optional: include N in the output config is ignored when for_reinit is True
for_reinit: bool, optional: include the parameters that need reinitialization of the simulation core session if changed

Returns¶

config: dict: dictionary of simulation group configuration

score(emp_fc_tril=None, emp_fcd_tril=None, emp_bold=None, fic_penalty_scale=2)¶

Calcualates individual goodness-of-fit terms and aggregates them. In FIC models also calculates fic_penalty.

Parameters¶

emp_fc_tril: np.ndarray: 1D array of empirical FC lower triangle. Shape: (edges,)
emp_fcd_tril: np.ndarray: 1D array of empirical FCD lower triangle. Shape: (window_pairs,)
emp_bold: np.ndarray or None: cleaned and parcellated empirical BOLD time series. Shape: (nodes, volumes) Motion outliers should either be excluded (not recommended as it disrupts the temporal structure) or replaced with zeros. If provided emp_fc_tril and emp_fcd_tril will be ignored.
fic_penalty_scale: float, optional: scale of the FIC penalty term. Set to 0 to disable the FIC penalty term. Note that while it is included in the cost function of optimizer, it is not included in the aggregate GOF

Returns¶

scores: pd.DataFrame: The goodness of fit measures (columns) of each simulation (rows)

clear()¶: Clear the simulation outputs

run(force_reinit=False)¶

Run the simulations in parallel (as possible) on GPU/CPU through the cubnm._core.run_simulations() function which runs compiled C++/CUDA code.

Parameters¶

force_reinit: bool, optional: force reinitialization of the session. At the beginning of each session (when cubnm is imported) some variables are initialized on CPU/GPU and reused in every run. Set this to True if you want to reinitialize these variables. This is rarely needed.

get_noise()¶

Returns¶

noise: np.ndarray: Noise segment array. Shape: (n_noise, nodes, time_steps, 10)

save(save_as='npz')¶

Save simulation outputs to disk.

Parameters¶

save_as: {‘npz’ or ‘txt’}, optional

‘npz’: all the output of all sims will be written to a npz file
‘txt’: outputs of simulations will be written to separate files, recommended when N = 1 (e.g. rerunning the best simulation)

class cubnm.sim.rWWExSimGroup(*args, **kwargs)¶

Bases: SimGroup

Group of reduced Wong-Wang simulations (excitatory only, Deco 2013) that are executed in parallel

Parameters¶

*args, **kwargs:: see cubnm.sim.SimGroup for details

Attributes¶

param_lists: dict of np.ndarray

dictionary of parameter lists, including

‘G’: global coupling. Shape: (N_SIMS,)
‘w’: local excitatory self-connection strength. Shape: (N_SIMS, nodes)
‘I0’: local external input current. Shape: (N_SIMS, nodes)
‘sigma’: local noise sigma. Shape: (N_SIMS, nodes)
‘v’: conduction velocity. Shape: (N_SIMS,)

Example¶

To see example usage in grid search and evolutionary algorithms see cubnm.optimize.

Here, as an example on how to use SimGroup independently, we will run a single simulation and save the outputs to disk.

from cubnm import sim, datasets

sim_group = sim.rWWExSimGroup(
    duration=60,
    TR=1,
    sc=datasets.load_sc('strength', 'schaefer-100'),
)
sim_group.N = 1
sim_group.param_lists['G'] = np.repeat(0.5, N_SIMS)
sim_group.param_lists['w'] = np.full((N_SIMS, nodes), 0.9)
sim_group.param_lists['I0'] = np.full((N_SIMS, nodes), 0.3)
sim_group.param_lists['sigma'] = np.full((N_SIMS, nodes), 0.001)
sim_group.run()

model_name = 'rWWEx'¶

global_param_names = ['G']¶

regional_param_names = ['w', 'I0', 'sigma']¶

state_names = ['x', 'r', 'S']¶

sel_state_var = 'r'¶

n_noise = 1¶

get_config(include_N=False, for_reinit=False)¶

Get the configuration of the simulation group

Parameters¶

include_N: bool, optional: include N in the output config is ignored when for_reinit is True
for_reinit: bool, optional: include the parameters that need reinitialization of the simulation core session if changed

Returns¶

config: dict: dictionary of simulation group configuration

run(force_reinit=False)¶

Run the simulations in parallel (as possible) on GPU/CPU through the cubnm._core.run_simulations() function which runs compiled C++/CUDA code.

Parameters¶

force_reinit: bool, optional: force reinitialization of the session. At the beginning of each session (when cubnm is imported) some variables are initialized on CPU/GPU and reused in every run. Set this to True if you want to reinitialize these variables. This is rarely needed.

get_noise()¶

Returns¶

noise: np.ndarray: Noise segment array. Shape: (n_noise, nodes, time_steps, 10)

clear()¶: Clear the simulation outputs

score(emp_fc_tril=None, emp_fcd_tril=None, emp_bold=None)¶

Calcualates individual goodness-of-fit terms and aggregates them.

Parameters¶

emp_fc_tril: np.ndarray or None: 1D array of empirical FC lower triangle. Shape: (edges,)
emp_fcd_tril: np.ndarray or None: 1D array of empirical FCD lower triangle. Shape: (window_pairs,)
emp_bold: np.ndarray or None: cleaned and parcellated empirical BOLD time series. Shape: (nodes, volumes) Motion outliers should either be excluded (not recommended as it disrupts the temporal structure) or replaced with zeros. If provided emp_fc_tril and emp_fcd_tril will be ignored.

Returns¶

scores: pd.DataFrame: The goodness of fit measures (columns) of each simulation (rows)

save(save_as='npz')¶

Save simulation outputs to disk.

Parameters¶

save_as: {‘npz’ or ‘txt’}, optional

‘npz’: all the output of all sims will be written to a npz file
‘txt’: outputs of simulations will be written to separate files, recommended when N = 1 (e.g. rerunning the best simulation)

class cubnm.sim.KuramotoSimGroup(*args, random_init_theta=True, **kwargs)¶

Bases: SimGroup

Group of Kuramoto simulations that are executed in parallel

Parameters¶

*args, **kwargs:: see cubnm.sim.SimGroup for details
random_init_thetabool, optional: Set initial theta by randomly sampling from a uniform distribution [0, 2*pi].

Attributes¶

param_lists: dict of np.ndarray

dictionary of parameter lists, including

‘G’: global coupling. Shape: (N_SIMS,)
‘init_theta’: initial theta. Randomly sampled from a uniform distribution
[0, 2*pi] by default. Shape: (N_SIMS, nodes)
‘omega’: intrinsic frequency. Shape: (N_SIMS, nodes)
‘sigma’: local noise sigma. Shape: (N_SIMS, nodes)
‘v’: conduction velocity. Shape: (N_SIMS,)

Example¶

To see example usage in grid search and evolutionary algorithms see cubnm.optimize.

Here, as an example on how to use SimGroup independently, we will run a single simulation and save the outputs to disk.

from cubnm import sim, datasets

sim_group = sim.KuramotoSimGroup(
    duration=60,
    TR=1,
    sc=datasets.load_sc('strength', 'schaefer-100'),
)
sim_group.N = 1
sim_group.param_lists['G'] = np.repeat(0.5, N_SIMS)
sim_group.param_lists['omega'] = np.full((N_SIMS, nodes), np.pi)
sim_group.param_lists['sigma'] = np.full((N_SIMS, nodes), 0.17)
sim_group.run()

model_name = 'Kuramoto'¶

global_param_names = ['G']¶

regional_param_names = ['init_theta', 'omega', 'sigma']¶

state_names = ['theta']¶

sel_state_var = 'theta'¶

n_noise = 1¶

get_config(include_N=False, for_reinit=False)¶

Get the configuration of the simulation group

Parameters¶

include_N: bool, optional: include N in the output config is ignored when for_reinit is True
for_reinit: bool, optional: include the parameters that need reinitialization of the simulation core session if changed

Returns¶

config: dict: dictionary of simulation group configuration

run(force_reinit=False)¶

Run the simulations in parallel (as possible) on GPU/CPU through the cubnm._core.run_simulations() function which runs compiled C++/CUDA code.

Parameters¶

force_reinit: bool, optional: force reinitialization of the session. At the beginning of each session (when cubnm is imported) some variables are initialized on CPU/GPU and reused in every run. Set this to True if you want to reinitialize these variables. This is rarely needed.

get_noise()¶

Returns¶

noise: np.ndarray: Noise segment array. Shape: (n_noise, nodes, time_steps, 10)

clear()¶: Clear the simulation outputs

score(emp_fc_tril=None, emp_fcd_tril=None, emp_bold=None)¶

Calcualates individual goodness-of-fit terms and aggregates them.

Parameters¶

emp_fc_tril: np.ndarray or None: 1D array of empirical FC lower triangle. Shape: (edges,)
emp_fcd_tril: np.ndarray or None: 1D array of empirical FCD lower triangle. Shape: (window_pairs,)
emp_bold: np.ndarray or None: cleaned and parcellated empirical BOLD time series. Shape: (nodes, volumes) Motion outliers should either be excluded (not recommended as it disrupts the temporal structure) or replaced with zeros. If provided emp_fc_tril and emp_fcd_tril will be ignored.

Returns¶

scores: pd.DataFrame: The goodness of fit measures (columns) of each simulation (rows)

save(save_as='npz')¶

Save simulation outputs to disk.

Parameters¶

save_as: {‘npz’ or ‘txt’}, optional

‘npz’: all the output of all sims will be written to a npz file
‘txt’: outputs of simulations will be written to separate files, recommended when N = 1 (e.g. rerunning the best simulation)

class cubnm.sim.MultiSimGroupMixin(sim_groups)¶

Mixin for combining multiple simulation groups into one, which is intended for batch optimization, i.e. running multiple optimizations at the same time on GPU.

run(**kwargs)¶

Runs merged simulations of all children by concatenating SCs and parameters and then running all simulations in parallel as a single merged simulation group.

Parameters¶

**kwargs: keyword arguments to be passed to cubnm.sim.SimGroup.run method

cubnm.sim.create_multi_sim_group(sim_group_cls)¶

Dynamically creates a MultiSimGroup class by combining a model’s specific <Model>SimGroup class with MultiSimGroupMixin, which can be used in batch optimization.

Parameters¶

sim_group_cls: type: e.g. rWWSimGroup, rWWExSimGroup, KuramotoSimGroup

Returns¶

MultiSimGroup: type: MultiSimGroup class that can be used in batch optimization

cubnm.sim¶

Parameters¶

Attributes¶

Notes¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Parameters¶

Parameters¶

Attributes¶

Example¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Parameters¶

Parameters¶

Attributes¶

Example¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Parameters¶

Parameters¶

Attributes¶

Example¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Parameters¶

Parameters¶

Parameters¶

Returns¶

`cubnm.sim`¶