backend Package

base

Simulator backends provide pluggable numerical implementations, allowing for different implementations or strategies.

• Follows roughly the DAO pattern which isolates the service layer from database API - current simulator+datatypes is the compute “service” - backends back the compute service - service layer passes traited types into backend - backend handles the translation to a particular compute api (numpy, tf)

• Isolates array creation, tracing, assist switching in float32

• ‘Service’ layer receives closures or generator

• Backend specifies preferred types and array creation routines

• Components can then be associated with a backend, e.g. - nest component uses nest backend - field component uses shtns backend

• Multibackend-multicomponents need conversions done

class tvb.simulator.backend.base.BaseBackend

Bases: object

Type tag for backends.

static default(self)

Get default backend.

cu

A CUDA backend which uses templating to generate simulation code, with PyCUDA as the driver.

class tvb.simulator.backend.cu.CuBackend

Bases: MakoUtilMix

build_func(template_source, content, name='kernel', print_source=False)

Build and retrieve a Python function from template.

nb

A Numba backend based on the NumPy backend.

… moduleauthor:: Marmaduke Woodman <marmaduke.woodman@univ-amu.fr>

class tvb.simulator.backend.nb.NbBackend

Bases: NpBackend

nb_mpr

Numba backend which uses templating to generate simulation code.

class tvb.simulator.backend.nb_mpr.NbMPRBackend

Bases: MakoUtilMix

build_py_func(template_source, content, name='kernel', print_source=False, modname=None)

Build and retrieve one or more Python functions from template.

check_compatibility(sim)

eval_module(source, name, modname)

eval_source(source, name)

run_sim(sim, nstep=None, simulation_length=None, chunksize=100000, compatibility_mode=False, print_source=False)

np

A plain NumPy backend which uses templating to generate simulation code.

class tvb.simulator.backend.np.NpBackend

Bases: MakoUtilMix

build_py_func(template_source, content, name='kernel', print_source=False, modname=None, fname=None)

Build and retrieve one or more Python functions from template.

check_compatibility(sim)

eval_module(source, name, modname)

eval_source(source, name, print_source)

run_sim(sim, nstep=None, simulation_length=None, print_source=False)

ref

This module provides a reference backend implemented with NumPy.

class tvb.simulator.backend.ref.RefBase

Bases: object

Base methods for reference NumPy backend

static add_at()

at(a, indices, b=None, /)

Performs unbuffered in place operation on operand ‘a’ for elements specified by ‘indices’. For addition ufunc, this method is equivalent to a[indices] += b, except that results are accumulated for elements that are indexed more than once. For example, a[[0,0]] += 1 will only increment the first element once because of buffering, whereas add.at(a, [0,0], 1) will increment the first element twice.

New in version 1.8.0.

Parameters

aarray_like

The array to perform in place operation on.

indicesarray_like or tuple

Array like index object or slice object for indexing into first operand. If first operand has multiple dimensions, indices can be a tuple of array like index objects or slice objects.

barray_like

Second operand for ufuncs requiring two operands. Operand must be broadcastable over first operand after indexing or slicing.

Examples

Set items 0 and 1 to their negative values:

>>> a = np.array([1, 2, 3, 4])
>>> np.negative.at(a, [0, 1])
>>> a
array([-1, -2,  3,  4])

Increment items 0 and 1, and increment item 2 twice:

>>> a = np.array([1, 2, 3, 4])
>>> np.add.at(a, [0, 1, 2, 2], 1)
>>> a
array([2, 3, 5, 4])

Add items 0 and 1 in first array to second array, and store results in first array:

>>> a = np.array([1, 2, 3, 4])
>>> b = np.array([1, 2])
>>> np.add.at(a, [0, 1], b)
>>> a
array([2, 4, 3, 4])

static evaluate(ex: str, local_dict: Dict | None = None, global_dict: Dict | None = None, out: ndarray | None = None, order: str = 'K', casting: str = 'safe', _frame_depth: int = 3, **kwargs) → ndarray

Evaluate a simple array expression element-wise using the virtual machine.

Parameters

ex: str

a string forming an expression, like “2*a+3*b”. The values for “a” and “b” will by default be taken from the calling function’s frame (through use of sys._getframe()). Alternatively, they can be specified using the ‘local_dict’ or ‘global_dict’ arguments.

local_dict: dictionary, optional

A dictionary that replaces the local operands in current frame.

global_dict: dictionary, optional

A dictionary that replaces the global operands in current frame.

out: NumPy array, optional

An existing array where the outcome is going to be stored. Care is required so that this array has the same shape and type than the actual outcome of the computation. Useful for avoiding unnecessary new array allocations.

order: {‘C’, ‘F’, ‘A’, or ‘K’}, optional

Controls the iteration order for operands. ‘C’ means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements appear in memory as possible. For efficient computations, typically ‘K’eep order (the default) is desired.

casting: {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur when making a copy or buffering. Setting this to ‘unsafe’ is not recommended, as it can adversely affect accumulations.

• ‘no’ means the data types should not be cast at all.

• ‘equiv’ means only byte-order changes are allowed.

• ‘safe’ means only casts which can preserve values are allowed.

• ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.

• ‘unsafe’ means any data conversions may be done.

_frame_depth: int

The calling frame depth. Unless you are a NumExpr developer you should not set this value.

Note

Both validate and by extension evaluate call eval(ex), which is potentially dangerous on unsanitized inputs. As such, NumExpr does some sanitization, banning the character ‘:;[’, the dunder ‘__’, and attribute access to all but ‘.r’ for real and ‘.i’ for imag access to complex numbers.

static heaviside(array)

heaviside() returns 1 if argument > 0, 0 otherwise.

The copy operation here is necessary to ensure that the array passed in is not modified.

static iround(number) → integer

Trying to get a stable and portable result when rounding a number to the nearest integer.

NOTE: I’m introducing this because of the unstability we found when using int(round()). Should use always the same rounding strategy.

Try : >>> int(4.999999999999999) 4 >>> int(4.99999999999999999999) 5

static linear_interp1d(start_time, end_time, start_value, end_value, interp_point)

performs a one dimensional linear interpolation using two timepoints (start_time, end_time) for two floating point (possibly NumPy arrays) states (start_value, end_value) to return state at timepoint start_time < interp_point < end_time.

numexpr = <module 'numexpr' from '/opt/conda/envs/tvb-docs/lib/python3.10/site-packages/numexpr/__init__.py'>

class tvb.simulator.backend.ref.RefSurface

Bases: RefBase

Surface/field-related methods.

static surface_state_to_rois(_regmap, n_reg, state)

class tvb.simulator.backend.ref.ReferenceBackend

Bases: BaseBackend, RefSurface

Base reference backend, implemented in readable NumPy.

Subpackages

• templates Package
  • MakoUtilMix
    • MakoUtilMix.insert_line_numbers()
    • MakoUtilMix.lookup
    • MakoUtilMix.render_template()
  • Subpackages