# graph { #tvbo.run.graph }

`run.graph`

Graph-based simulation of a connectome as a network of coupled local models.

This module provides [`GraphRunner`](/api/run/graph.qmd#GraphRunner), which turns a connectome into a `networkx` graph, attaches a local dynamics model to each node and a coupling to each edge, and integrates the resulting network in time using the helpers in [`tvbo.run.compgraph`](/api/run/compgraph.qmd).

## Classes

| Name | Description |
| --- | --- |
| [GraphRunner](#tvbo.run.graph.GraphRunner) | Assemble and integrate a connectome as a network of coupled local models. |

### GraphRunner { #tvbo.run.graph.GraphRunner }

```python
run.graph.GraphRunner(connectome, normalize_weights=True)
```

Assemble and integrate a connectome as a network of coupled local models.

A `GraphRunner` holds a `networkx` graph snapshot built from a connectome.
Node attributes carry the local dynamics model, its integrated state and optional stimulus; edge attributes carry the coupling. After the local models, couplings and stimuli have been attached, [`run`](/api/run/graph.qmd#GraphRunner.run) compiles per-node and per-edge functions and integrates the network in time.

The integrator reads one edge per node pair: a multigraph snapshot is flattened to a simple digraph at construction, and true parallel edges (typed projections between the same pair) are rejected with a `ValueError`.

#### Parameters {.doc-section .doc-section-parameters}

| Name              | Type   | Description                                                                                                                                                                     | Default    |
|-------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| connectome        |        | Connectome whose weights and node/edge structure define the network. Its `create_graph` method supplies the graph snapshot.                                                     | _required_ |
| normalize_weights |        | When `True`, normalize the connectome weights via the connectome's schema-safe `normalize_weights` method before building the graph. Failures during normalization are ignored. | `True`     |

#### Methods

| Name | Description |
| --- | --- |
| [add_coupling](#tvbo.run.graph.GraphRunner.add_coupling) | Attach a coupling function to the graph edges. |
| [add_local_model](#tvbo.run.graph.GraphRunner.add_local_model) | Attach a local dynamics model to the graph nodes. |
| [add_stimulus](#tvbo.run.graph.GraphRunner.add_stimulus) | Attach a stimulus to a single node. |
| [run](#tvbo.run.graph.GraphRunner.run) | Integrate the network in time and return the simulated time series. |
| [setup_cfuns](#tvbo.run.graph.GraphRunner.setup_cfuns) | Compile each edge's coupling into callable coupling functions. |
| [setup_dfuns](#tvbo.run.graph.GraphRunner.setup_dfuns) | Compile each node's model into a callable derivative function. |
| [setup_initial_conditions](#tvbo.run.graph.GraphRunner.setup_initial_conditions) | Initialize each node's state from its model's initial values. |
| [setup_stimulation](#tvbo.run.graph.GraphRunner.setup_stimulation) | Compile stimulus functions for every stimulated node. |
| [to_yaml](#tvbo.run.graph.GraphRunner.to_yaml) | Export Network to YAML format. |

##### add_coupling { #tvbo.run.graph.GraphRunner.add_coupling }

```python
run.graph.GraphRunner.add_coupling(coupling)
```

Attach a coupling function to the graph edges.

The snapshot is a simple digraph (see `__init__`), so edges are keyed by `(source, target)`.

###### Parameters {.doc-section .doc-section-parameters}

| Name     | Type   | Description                                                                                                                                                                                                                                                               | Default    |
|----------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| coupling |        | A [`Coupling`](../classes/coupling.qmd#Coupling) instance, a deep copy of which is assigned to every edge; a bare datamodel `Coupling`, which is wrapped in a `Coupling` and then copied to every edge; or a dict mapping `(source, target)` pairs to per-edge couplings. | _required_ |

##### add_local_model { #tvbo.run.graph.GraphRunner.add_local_model }

```python
run.graph.GraphRunner.add_local_model(model)
```

Attach a local dynamics model to the graph nodes.

###### Parameters {.doc-section .doc-section-parameters}

| Name   | Type   | Description                                                                                                                 | Default    |
|--------|--------|-----------------------------------------------------------------------------------------------------------------------------|------------|
| model  |        | A single `Model`/`Dynamics` instance applied to every node, or a dict mapping node identifiers to per-node model instances. | _required_ |

##### add_stimulus { #tvbo.run.graph.GraphRunner.add_stimulus }

```python
run.graph.GraphRunner.add_stimulus(
    node,
    stimulus,
    stvar=None,
    as_derived_variable=False,
)
```

Attach a stimulus to a single node.

###### Parameters {.doc-section .doc-section-parameters}

| Name                | Type   | Description                                                                                                                              | Default    |
|---------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------|------------|
| node                |        | Identifier of the node to stimulate.                                                                                                     | _required_ |
| stimulus            |        | Stimulus to apply at that node.                                                                                                          | _required_ |
| stvar               |        | State variable name, or list of names, to mark as stimulation targets on the node's model. Ignored when `as_derived_variable` is `True`. | `None`     |
| as_derived_variable |        | When `True`, add the stimulus to the node's model as a derived variable instead of storing it on the node and flagging state variables.  | `False`    |

##### run { #tvbo.run.graph.GraphRunner.run }

```python
run.graph.GraphRunner.run(duration=1000, dt=1, format='graph')
```

Integrate the network in time and return the simulated time series.

Sets up initial conditions, stimulation, node derivative functions and edge coupling functions, initializes the delay history buffer, then integrates the network dynamics with delays and collects the resulting time series.

###### Parameters {.doc-section .doc-section-parameters}

| Name     | Type   | Description                                        | Default   |
|----------|--------|----------------------------------------------------|-----------|
| duration |        | Total simulation time, in the model's time units.  | `1000`    |
| dt       |        | Integration time step.                             | `1`       |
| format   |        | Reserved output-format selector; currently unused. | `'graph'` |

###### Returns {.doc-section .doc-section-returns}

| Name   | Type   | Description                                                     |
|--------|--------|-----------------------------------------------------------------|
|        |        | The collected per-node time series over the simulated interval. |

##### setup_cfuns { #tvbo.run.graph.GraphRunner.setup_cfuns }

```python
run.graph.GraphRunner.setup_cfuns()
```

Compile each edge's coupling into callable coupling functions.

For every edge, stores the compiled `python` coupling function under `"cfun"`, `"prefun"` and `"postfun"` lambdas obtained by substituting the coupling's parameter values into its pre- and post-summation expressions, and `"post_src"`, the substituted post expression the integrator compares to reject mixed post-transforms on one node.

##### setup_dfuns { #tvbo.run.graph.GraphRunner.setup_dfuns }

```python
run.graph.GraphRunner.setup_dfuns()
```

Compile each node's model into a callable derivative function.

Stores the compiled `python-network` derivative function under the `"dfun"` attribute of every node.

##### setup_initial_conditions { #tvbo.run.graph.GraphRunner.setup_initial_conditions }

```python
run.graph.GraphRunner.setup_initial_conditions()
```

Initialize each node's state from its model's initial values.

Stores, under each node's `"state"` attribute, an array of the initial values of the model's state variables.

##### setup_stimulation { #tvbo.run.graph.GraphRunner.setup_stimulation }

```python
run.graph.GraphRunner.setup_stimulation(sampling_rate=500, duration=2000)
```

Compile stimulus functions for every stimulated node.

For each node that carries a non-`None` `"stimulus"`, compiles the stimulus to a `python` callable sampled at `sampling_rate` over the stimulus's own duration and stores it under the node's `"stimfun"` attribute.

###### Parameters {.doc-section .doc-section-parameters}

| Name          | Type   | Description                                                | Default   |
|---------------|--------|------------------------------------------------------------|-----------|
| sampling_rate |        | Sampling rate, in Hz, at which each stimulus is evaluated. | `500`     |
| duration      |        | Unused; each stimulus is sampled over its own duration.    | `2000`    |

##### to_yaml { #tvbo.run.graph.GraphRunner.to_yaml }

```python
run.graph.GraphRunner.to_yaml(format='tvbo', filepath=None)
```

Export Network to YAML format.



###### Parameters {.doc-section .doc-section-parameters}

format : str
    Output format: "tvbo" (default) or "pyrates" for PyRates CircuitTemplate.
filepath : str, optional
    Path to write the YAML file. If None, returns the YAML string.



###### Returns: {.doc-section .doc-section-returns}

str
    YAML string (or filepath if written to file).