goflow.models.base

class goflow.models.base.model

Bases: object

The basic model class, acting as a center piece for ‘morph’ simulations, as it defines the individual dynamic system.

This class defines the ODE sytem, metabolic cost model and a diverse set of functionalities for effective evaluation of any simulation’s proceeding. Based on scipy.integrate.solve_ivp (1.7.3) it defines specific event handlers for stiff systems and utility functions.

Attributes:

ivp_options (dict):

Information to generate the internal solver_options. Providing t0,t1 number of evaluation and x0.

model_args (list):

Model specific paramerets need to evaluate the update rules of the DS

solver_options (dict):

Specifying runtime and evaluation marks.

events (dict):

Events to consier, here in gernal flatlining events which allow for early termination of stiff simulations.

null_decimals (in):

description

Methods:

init()

The model post_init function.

update_event_func()

Update the event function and ensures that solver_options are set.

flatlining_default(t, x_0, *args)

The default flatlining function for determining the terminal event of the dynamical system.

flatlining_dynamic(t, x_0, *args)

The dynamic flatlining function for determining the terminal event of the dynamical system.

set_model_parameters(model_pars)

Set internal model arguments array.

set_solver_options(solv_opt)

Set internal solver_options and update event function.

calc_update_stimuli(t, x_0, *args)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

calc_cost_stimuli(t, x_0, *args)

Computes the dynamic system’s Lyapunov function and its gradient.

calc_cost_stimuli(t, x_0, *args)

Computes the dynamic system’s Lyapunov function and its gradient.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus ] functions

Returns:

iterable:

The computed gradient dF to the current cost function F, as well as F itself.

calc_update_stimuli(t, x_0, *args)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus functions

Returns:

array:

The computed change dx to the state vector x_0.

f(t, x_0, *args)

The dynamic flatlining function for determining the terminal event of the dynamical system.

Based on the event handling schemes of scipy.integrate.solve_ivp (1.7.3), has the same call signature as calc_update_stimuli(). The method checks whether the magnitude of relative change of the state vector x_0 has decreased beneath a certain threshold.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, same signature as needed for calc_update_stimuli.

Returns:

float:

z, the signature of sign change, signaling the internal threshold being passed.

flatlining_default(t, x_0, *args)

The default flatlining function for determining the terminal event of the dynamical system.

Based on the event handling schemes of scipy.integrate.solve_ivp (1.7.3), has the same call signature as calc_update_stimuli(). The method checks whether the system’s Lyapunov function has decreased beneath a certain threshold.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, same signature as needed for calc_update_stimuli.

Returns:

float:

z, the signature of sign change, signaling the internal threshold being passed.

flatlining_dynamic(t, x_0, *args)

The dynamic flatlining function for determining the terminal event of the dynamical system.

Based on the event handling schemes of scipy.integrate.solve_ivp (1.7.3), has the same call signature as calc_update_stimuli(). The method checks whether the magnitude of relative change of the state vector x_0 has decreased beneath a certain threshold.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, same signature as needed for calc_update_stimuli.

Returns:

float:

z, the signature of sign change, signaling the internal threshold being passed.

init()

The model post_init function.

Setting proxy values for internal variables.

set_model_parameters(model_pars)

Set internal model arguments array.

Args:

model_pars (dict):

Model argument dictionary generated on program initilization.

set_solver_options(solv_opt)

Set internal solver_options and update event function.

Args:

solv_opt (dict):

Solver argument dictionary generated on program initilization.

update_event_func()

Update the event function and ensures that solver_options are set.

Raises:

Exception: n

Warning: Event handling got inadequadt event function, falling back to default

goflow.models.murray

class goflow.models.murray.murray(pars: dict = <factory>)

Bases: goflow.models.base.model

The network adaptation model according to Murray, based on flow dissipation-volume minimization as published in:

Murray, The Physiological Principle of Minimum Work, PNAS, 1926

The system’s cost function is given as:

\[\Gamma = \sum_{e}\left(\frac{f_e^2}{C_e} + ar_e^2\right)\]

For minimizing this cost one iteratively computes the flow f_e, pressure Delta p_e landscapes. The system’s derived gradient descent dynamics are given as:

\[\frac{dr_e}{dt} \propto \left[\alpha_1\left( \frac{\Delta p_er_e}{L_e}\right)^2-\alpha_0\right] r_e\]

Attributes:

pars (dict):

The specific model parameters alpha_0, alpha_1.

ivp_options (dict):

Information to generate the internal solver_options. Providing t0,t1 number of evaluation and x0.

model_args (list):

Model specific paramerets need to evaluate the update rules of the DS

solver_options (dict):

Specifying runtime and evaluation marks.

events (dict):

Events to consier, here in gernal flatlining events which allow for early termination of stiff simulations.

null_decimals (in):

description

Methods:

init()

The model post_init function.

update_event_func()

Update the event function and ensures that solver_options are set.

flatlining_default(t, x_0, *args)

The default flatlining function for determining the terminal event of the dynamical system.

flatlining_dynamic(t, x_0, *args)

The dynamic flatlining function for determining the terminal event of the dynamical system.

set_model_parameters(model_pars)

Set internal model arguments array.

set_solver_options(solv_opt)

Set internal solver_options and update event function.

calc_update_stimuli(t, x_0, *args)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

calc_cost_stimuli(t, x_0, *args)

Computes the dynamic system’s Lyapunov function and its gradient.

get_stimuli_pars(self, flow, x_0)

Update flow & pressure landscapes, recompute conductivity as well as squared quantities.

calc_cost_stimuli(t, x_0, flow, alpha_0, alpha_1)

Computes the dynamic system’s Lyapunov function and its gradient.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus ] functions

Returns:

iterable:

The computed gradient dF to the current cost function F, as well as F itself.

calc_update_stimuli(t, x_0, flow, alpha_0, alpha_1)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus functions

Returns:

array:

The computed change dx to the state vector x_0.

get_stimuli_pars(flow, x_0)

Update flow & pressure landscapes, recompute conductivity as well as squared quantities.

Invokes the internal flow circuit and recalcs flows and pressures as well as conductivities according to Hagen-Poiseuille’s law of flows in cylindrical pipes.

Args:

flow (flow):

A hailhydro flow object, describing the current flow landscape in the transport network.

x_0 (array):

Current state vector of the dynmic system.

Returns:

iterable:

The squared state vector as well as the squared pressure landscape x_sq, p_sq

set_model_parameters(model_pars)

Set internal model arguments array.

Args:

model_pars (dict):

Model argument dictionary generated on program initilization.

set_solver_options(solv_opt)

Set internal solver_options and update event function.

Args:

solv_opt (dict):

Solver argument dictionary generated on program initilization.

goflow.models.bohn

class goflow.models.bohn.bohn(pars: dict = <factory>)

Bases: goflow.models.murray.murray

The network adaptation model according to Bohn et al, based on flow dissipation-volume minimization with reweightedscales of conductivity costs as published for example:

Katifori et al, Damage and Fluctuations Induce Loops in Optimal Transport Networks, PRL,2010

The system’s cost function is given as:

\[\Gamma = \sum_{e}\left(\frac{f_e^2}{C_e} + aC_e^{\gamma}\right)\]

For minimizing this cost one iteratively computes the flow f_e, pressure Delta p_e landscapes. The system’s derived gradient descent dynamics are given as:

\[\frac{dr_e}{dt} \propto \left[\alpha_1\left( \frac{\Delta p_e}{L_e}\right)^2\frac{C_e}{r_e^{4\gamma}}-\alpha_0 \right] r_e\]

Attributes:

pars (dict):

The specific model parameters alpha_0, alpha_1 and rescaling factor gamma.

ivp_options (dict):

Information to generate the internal solver_options. Providing t0,t1 number of evaluation and x0.

model_args (list):

Model specific paramerets need to evaluate the update rules of the DS

solver_options (dict):

Specifying runtime and evaluation marks.

events (dict):

Events to consier, here in gernal flatlining events which allow for early termination of stiff simulations.

null_decimals (in):

description

Methods:

init()

The model post_init function.

update_event_func()

Update the event function and ensures that solver_options are set.

flatlining_default(t, x_0, *args)

The default flatlining function for determining the terminal event of the dynamical system.

flatlining_dynamic(t, x_0, *args)

The dynamic flatlining function for determining the terminal event of the dynamical system.

set_model_parameters(model_pars)

Set internal model arguments array.

set_solver_options(solv_opt)

Set internal solver_options and update event function.

calc_update_stimuli(t, x_0, *args)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

calc_cost_stimuli(t, x_0, *args)

Computes the dynamic system’s Lyapunov function and its gradient.

get_stimuli_pars(self, flow, x_0)

Update flow & pressure landscapes, recompute conductivity as well as squared quantities.

calc_cost_stimuli(t, x_0, flow, alpha_0, alpha_1, gamma)

Computes the dynamic system’s Lyapunov function and its gradient.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus ] functions

Returns:

iterable:

The computed gradient dF to the current cost function F, as well as F itself.

calc_update_stimuli(t, x_0, flow, alpha_0, alpha_1, gamma)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus functions

Returns:

array:

The computed change dx to the state vector x_0.

get_stimuli_pars(flow, x_0)

Update flow & pressure landscapes, recompute conductivity as well as squared quantities.

Invokes the internal flow circuit and recalcs flows and pressures as well as conductivities according to Hagen-Poiseuille’s law of flows in cylindrical pipes.

Args:

flow (flow):

A hailhydro flow object, describing the current flow landscape in the transport network.

x_0 (array):

Current state vector of the dynmic system.

Returns:

iterable:

The squared state vector as well as the squared pressure landscape x_sq, p_sq

set_model_parameters(model_pars)

Set internal model arguments array.

Args:

model_pars (dict):

Model argument dictionary generated on program initilization.

goflow.models.corson

class goflow.models.corson.corson(pars: dict = <factory>)

Bases: goflow.models.murray.murray

The network adaptation model according to Bohn et al, based on flow dissipation-volume minimization with reweightedscales of conductivity costs as published for example:

Corson, Fluctuations and Redundancy in Optimal Transport Networks, PRL, 2010

Hu and Cai, Adaptation and Optimization of Biological Transport Networks, PRL, 2013

The approach assumes a varying sink-source landscape and a time scale separation between this variation and radial adaptation. The system’s cost function is given as:

\[\Gamma = \sum_{e}\left(C_e\langle \Delta p_e^2\rangle + aC_e^{\gamma}\right)\]

The system’s derived gradient descent dynamics are given as:

\[\frac{dr_e}{dt} \propto \left[\alpha_1 \frac{\langle \Delta p_e^2 \rangle }{L_e^2} \frac{C_e}{r_e^{4\gamma}}-\alpha_0\right] r_e\]

Attributes:

pars (dict):

The specific model parameters alpha_0, alpha_1, gamma and effective noise strength eta.

ivp_options (dict):

Information to generate the internal solver_options. Providing t0,t1 number of evaluation and x0.

model_args (list):

Model specific paramerets need to evaluate the update rules of the DS

solver_options (dict):

Specifying runtime and evaluation marks.

events (dict):

Events to consier, here in gernal flatlining events which allow for early termination of stiff simulations.

null_decimals (in):

description

Methods:

init()

The model post_init function.

update_event_func()

Update the event function and ensures that solver_options are set.

flatlining_default(t, x_0, *args)

The default flatlining function for determining the terminal event of the dynamical system.

flatlining_dynamic(t, x_0, *args)

The dynamic flatlining function for determining the terminal event of the dynamical system.

set_model_parameters(model_pars)

Set internal model arguments array.

set_solver_options(solv_opt)

Set internal solver_options and update event function.

calc_update_stimuli(t, x_0, *args)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

calc_cost_stimuli(t, x_0, *args)

Computes the dynamic system’s Lyapunov function and its gradient.

get_stimuli_pars(self, flow, x_0)

Update flow & pressure landscapes, recompute conductivity as well as squared quantities.

calc_cost_stimuli(t, x_0, flow, alpha_0, alpha_1, gamma, noise)

Computes the dynamic system’s Lyapunov function and its gradient.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus ] functions

Returns:

iterable:

The computed gradient dF to the current cost function F, as well as F itself.

calc_update_stimuli(t, x_0, flow, a_0, a_1, gm, noise)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus functions

Returns:

array:

The computed change dx to the state vector x_0.

get_stimuli_pars(flow, x_0)

Update flow & pressure landscapes, recompute conductivity as well as squared quantities.

Invokes the internal flow circuit and recalcs flows and pressures as well as conductivities according to Hagen-Poiseuille’s law of flows in cylindrical pipes.

Args:

flow (flow):

A hailhydro flow object, describing the current flow landscape in the transport network.

x_0 (array):

Current state vector of the dynmic system.

Returns:

iterable:

The squared state vector as well as the squared pressure landscape x_sq, p_sq

set_model_parameters(model_pars)

Set internal model arguments array.

Args:

model_pars (dict):

Model argument dictionary generated on program initilization.

goflow.models.meigel

class goflow.models.meigel.link(pars: dict = <factory>)

Bases: goflow.models.meigel.meigel

The network adaptation model according to Meigel/Horton et al, based on flow dissipation-volume minimization in combination with supply-demand competition of conductivity costs as published for example:

Kramer&Modes, On biological flow networks: Antagonism between hydrodynamic and metabolic stimuli as driver of topological transitions, arXiv:2111.04326

The system’s cost function is given as:

\[\Gamma = \sum_{e}\left( \alpha_1 r_e^4\Delta p_e^2 + \alpha_0 r_e^2 + \left[ \Phi_e-\Phi_0 \right]^2 \right)\]

Attributes:

pars (dict):

The specific model parameters alpha_0, alpha_1 and demand Phi_0

ivp_options (dict):

Information to generate the internal solver_options. Providing t0,t1 number of evaluation and x0.

model_args (list):

Model specific paramerets need to evaluate the update rules of the DS

solver_options (dict):

Specifying runtime and evaluation marks.

events (dict):

Events to consier, here in gernal flatlining events which allow for early termination of stiff simulations.

null_decimals (in):

description

Methods:

init()

The model post_init function.

update_event_func()

Update the event function and ensures that solver_options are set.

flatlining_default(t, x_0, *args)

The default flatlining function for determining the terminal event of the dynamical system.

flatlining_dynamic(t, x_0, *args)

The dynamic flatlining function for determining the terminal event of the dynamical system.

set_model_parameters(model_pars)

Set internal model arguments array.

set_solver_options(solv_opt)

Set internal solver_options and update event function.

calc_update_stimuli(t, x_0, *args)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

calc_cost_stimuli(t, x_0, *args)

Computes the dynamic system’s Lyapunov function and its gradient.

get_stimuli_pars(self, flow, x_0)

Update flow & pressure landscapes, recompute conductivity as well as squared quantities.

calc_cost_stimuli(t, x_0, flux, phi0, alpha_0, alpha_1)

Computes the dynamic system’s Lyapunov function and its gradient.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus ] functions

Returns:

iterable:

The computed gradient dF to the current cost function F, as well as F itself.

calc_update_stimuli(t, x_0, flux, phi0, alpha_0, alpha_1)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus functions

Returns:

array:

The computed change dx to the state vector x_0.

class goflow.models.meigel.meigel(pars: dict = <factory>)

Bases: goflow.models.base.model

The network adaptation model according to Meigel/Horton et al, based on minimization of supply-demand mismatch, with a simplified metabolite uptake model though:

Meigel et al, Flow rate of transport network controls uniform metabolite supply to tissue, Journal of the Royal Society Interface, 2018

Kramer&Modes, On biological flow networks: Antagonism between hydrodynamic and metabolic stimuli as driver of topological transitions, arXiv:2111.04326

The system’s cost function is given as:

\[\Gamma = \sum_{e} \left[ \Phi_e-\Phi_0 \right]^2\]

Attributes:

pars (dict):

The specific model parameters alpha_0, alpha_1 and demand Phi_0

ivp_options (dict):

Information to generate the internal solver_options. Providing t0,t1 number of evaluation and x0.

model_args (list):

Model specific paramerets need to evaluate the update rules of the DS

solver_options (dict):

Specifying runtime and evaluation marks.

events (dict):

Events to consier, here in gernal flatlining events which allow for early termination of stiff simulations.

null_decimals (in):

description

Methods:

init()

The model post_init function.

update_event_func()

Update the event function and ensures that solver_options are set.

flatlining_default(t, x_0, *args)

The default flatlining function for determining the terminal event of the dynamical system.

flatlining_dynamic(t, x_0, *args)

The dynamic flatlining function for determining the terminal event of the dynamical system.

set_model_parameters(model_pars)

Set internal model arguments array.

set_solver_options(solv_opt)

Set internal solver_options and update event function.

calc_update_stimuli(t, x_0, *args)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

calc_cost_stimuli(t, x_0, *args)

Computes the dynamic system’s Lyapunov function and its gradient.

get_stimuli_pars(self, flow, x_0)

Update flow & pressure landscapes, recompute conductivity as well as squared quantities.

calc_cost_stimuli(t, x_0, flux, phi0)

Computes the dynamic system’s Lyapunov function and its gradient.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus ] functions

Returns:

iterable:

The computed gradient dF to the current cost function F, as well as F itself.

calc_update_stimuli(t, x_0, flux, phi0)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus functions

Returns:

array:

The computed change dx to the state vector x_0.

goflow.models.kramer

class goflow.models.kramer.kramer(pars: dict = <factory>)

Bases: goflow.models.base.model

The network adaptation model for for two entangled networks, according to Kramer et al, based on minimization of noisy disspation-volume in combination with intertwinedness retrictions/couplings:

Kramer and Modes, How to pare a pair: Topology control and pruning in intertwined complex networks, PRR, 2020

The system’s cost function is given as:

\[\Gamma = \sum_{e} \left( C_e \langle \Delta p_e^2 \rangle + a r_e^{2} \right) + b \sum_{ee'} \Delta r_{ee'}^{\varepsilon}\]

Attributes:

pars (dict):

The specific model parameters p0 (growth rate), p1 (coupling), p2 (volume penalty), p3 (fluctuation) and coupling exponent varepsilon.

ivp_options (dict):

Information to generate the internal solver_options. Providing t0,t1 number of evaluation and x0.

model_args (list):

Model specific paramerets need to evaluate the update rules of the DS

solver_options (dict):

Specifying runtime and evaluation marks.

events (dict):

Events to consier, here in gernal flatlining events which allow for early termination of stiff simulations.

null_decimals (in):

description

Methods:

init()

The model post_init function.

update_event_func()

Update the event function and ensures that solver_options are set.

flatlining_default(t, x_0, *args)

The default flatlining function for determining the terminal event of the dynamical system.

flatlining_dynamic(t, x_0, *args)

The dynamic flatlining function for determining the terminal event of the dynamical system.

set_model_parameters(model_pars)

Set internal model arguments array.

set_solver_options(solv_opt)

Set internal solver_options and update event function.

calc_update_stimuli(t, x_0, *args)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

calc_cost_stimuli(t, x_0, *args)

Computes the dynamic system’s Lyapunov function and its gradient.

get_stimuli_pars(self, flow, x_0)

Update flow & pressure landscapes, recompute conductivity as well as squared quantities.

calc_update_stimuli(t, x_0, flow, p_0, p_1, p_2, p_3, coupling)

The dynamic system’s temporal update rule, computing the gradient -dF for dx/dt.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus functions

Returns:

array:

The computed change dx to the state vector x_0.

prune(t, x_0, flow, p_0, p_1, p_2, p_3, coupling)

Check whether a vessel collapsed, i.e. negative radii appear during integration. If so, handle it by pruning the vessel.

Args:

t (float):

Current time step in numeric ODE evaluation

x_0 (array):

Current state vector of the DS.

args (iterable):

Model specific tuple of parameters, needed to evaluate stimulus ] functions

Returns:

int:

1: do not prunr and keep updating 0: vessel collapsed, stop updating

set_solver_options(solv_opt)

Set internal solver_options and update event function.

Args:

solv_opt (dict):

Solver argument dictionary generated on program initilization.

update_event_func()

Update the event function and ensures that solver_options are set.

Raises:

Exception: n

Warning: Event handling got inadequadt event function, falling back to default