API Reference¶

`BondGraphTools`¶

class BondGraphTools.BondGraph(*args, **kwargs)[source]¶

Representation of a bond graph model.

property basis_vectors¶

Basis vectors for the state space (X), port space (J), and control space (U) from an external point of view.

For the state space dictionaries are of the form:

X = {
    sympy.Symbol('x_i'): (object, var)
}

We assume the object is a subclass of BondGraphBase and the var refers to the variable name in the objects local co-ordinate system and may be a string or a sympy.Symbol

For the port space, dictionaries are of the form:

J = {
    (sympy.Symbol(e_i), sympy.Symbol(f_i)): Port(obj, idx)
}

where Port is an instance of Port. Finally for the control variables we have:

U = {
    sympy.Symbol(u_i):(object, var)
}

Where object and var are specified as per the state space.

bonds¶: The list of connections between internal components

components¶: The components, instances of BondGraphBase, that make up this model

property constitutive_relations¶: The equations governing this objects dynamics.

property control_vars¶

A dict of all control variables in the form:

{
    "u_0": (component, control_var)
}

property internal_ports¶: A list of the ports internal to this model

map_port(label, ef)[source]¶: Exposes a pair of effort and flow variables as an external port :param label: The label to assign to this port. :param ef: The internal effort and flow variables.

property metamodel¶: The meta-model type of this object.

property params¶

A dictionary of parameters for this model in the form::: i: (component, param_name)

property state_vars¶

A dict of all state variables in the form:

{
   "x_0": (component, state_var)
}

Where “x_0” is the model state variable, and state_var is the corresponding state variable of component

system_model(control_vars=None)[source]¶

Produces a symbolic model of the system in reduced form.

In many cases it is useful to have a full description of the system in symbolic form, and not just a list of constitutive relations.

Returns: (coordinates, mappings, linear_op, nonlinear_op, constraints)

This method generates:

The model coordinate system (list) $x$

A mapping (dict) between the model coordinates and the component coordinates

A linear operator (sympy.Matrix) $L$

A nonlinear operator (sympy.Matrix) $F$

A list of constraints (sympy.Matrix) $G$

The coordinates are of the form

\[x = (dx_0, dx_1, \ldots, e_0, f_0, e_1, f_1, \ldots, x_0, x_1, \ldots, u_0, u_1, \ldots)\]

So that the system obeys the differential-algebraic equation

\[Lx + F(x) = 0 \qquad G(x) =0\]

See also

BondGraph.basis_vectors

property template¶: The model template from which this was created.

BondGraphTools.new(component=None, name=None, library='base', value=None, **kwargs)[source]¶

Creates a new Bond Graph from a library component.

Parameters

component (str or obj) – The type of component to create. If a string is specified, the the component will be created from the appropriate libaray. If an existing bond graph is given, the bond graph will be cloned.
name (str) – The name for the new component
library (str) – The library from which to find this component (if
string). (component is specified by) –
value –

Returns: instance of BondGraph

Raises: NotImplementedError

BondGraphTools.add(model, *args)[source]¶: Add the specified component(s) to the model

BondGraphTools.swap(old_component, new_component)[source]¶

Replaces the old component with a new component. Components must be of compatible classes; 1 one port cannot replace an n-port, for example. The old component will be completely removed from the system model.

Parameters

old_component – The component to be replaced. Must already be in the model.
new_component – The substitute component which must not be in the model

Raises

InvalidPortException, InvalidComponentException –

BondGraphTools.remove(model, component)[source]¶: Removes the specified components from the Bond Graph model.

BondGraphTools.connect(source, destination)[source]¶

Connects two components or ports.

Defines a power bond between the source and destination ports such that the bond tail is at the source, and the bond head is at the destination. We assume that either the source and/or destination is or has a free port.

Parameters

source (Port or BondGraphBase) – The tail of the power bond
destination (Port or BondGraphBase) – The head of the power bond

Raises

InvalidPortException, InvalidComponentException –

See also

disconnect()

BondGraphTools.disconnect(target, other)[source]¶

Disconnects the flow of energy between the two components or ports. If there is no connection, this method does nothing.

Parameters

target (Port, BondGraphBase) –
other (Port, BondGraphBase) –

Raises

InvalidComponentException –

See also

connect()

BondGraphTools.expose(component, label=None)[source]¶

Exposes the component as port on the parent.

If the target component is not a SS component, it is replaced with a new SS component. A new external port is added to the parent model, and connected to the SS component.

Parameters

component – The component to expose.
label – The label to assign to the external port

Raises: InvalidComponentException

BondGraphTools.set_param(component, param, value)[source]¶

Sets the specified parameter to a particular value.

Parameters

component (BondGraphBase) – The particular component.
param – The parameter to set
value – The value to assign it to, may be None

BondGraphTools.simulate(*args, **kwargs)[source]¶

Simulate the system dynamics.

This method integrates the dynamics of the system over the specified interval of time, starting at the specified initial state.

The solver used is a differential-algebraic integrator which respects conservation laws and algebraic constraints. It is expected that the initial state satisfies the systems inherent algebraic constrains; inconsistent initial conditions will raise exceptions.

The initial values of derivatives can be specified and the solver will ensure they are consistent with the initial state, or change them if they are not.

todo: detial control variables.

:param system BondGraph: The system to simulate :param timespan: A pair (list or tuple) containing the start and end

points of the simulation.

Parameters

x0 – The initial conditions of the system.
dx0 (Optional) – The initial rates of change of the system. The default value (None) indicates that the system should be initialised from the state variable initial conditions.
dt – The time step between reported (not integrated) values.
control_vars – A dict, list or tuple specifing the values of the control variables.

Returns

numpy array of timesteps x: numpy array of state values

Return type

t

Raises

ModelException, SolverException –

BondGraphTools.draw(system)[source]¶

Produces a network layout of the system.

Parameters: system – The system to visualise
Returns: matplotlib.Plot

`BondGraphTools.atomic`¶

This module contains class definitions for atomic components; those which cannot be decomposed into other components.

class BondGraphTools.atomic.Component(*args, **kwargs)[source]¶

Bases: BondGraphTools.base.BondGraphBase, BondGraphTools.port_managers.PortManager

Components defined by constitutive relations.

property basis_vectors¶: See BondGraphBase.basis_vectors

property constitutive_relations¶: See BondGraphBase

property control_vars¶: See BondGraphBase

property metamodel¶: The meta-model type of this object.

property params¶: See BondGraphBase

set_param(param, value)[source]¶: Warning: Scheduled to be deprecated

property state_vars¶: See BondGraphBase

property template¶: The model template from which this was created.

`BondGraphTools.base`¶

Base classes for bond graph models and connections.

class BondGraphTools.base.Bond(tail, head)[source]¶

Bases: BondGraphTools.base.Bond

Stores the connection between two ports.

Head and tail are specified to determine orientation

head¶: The ‘harpoon’ end of the power bond and direction of positive $f$

tail¶: The non-harpoon end, and direction of negative $f$

class BondGraphTools.base.BondGraphBase(*args, **kwargs)[source]¶

Bases: object

Base class definition for all bond graphs.

Parameters

name – Name of this model, assumed to be unique.
parent – Parent model, or none.
metamodel – Metamodel class.

property basis_vectors¶: The input/ouput, dynamic and interconnect vectors.

property constitutive_relations¶: The equations governing this objects dynamics.

property metamodel¶: The meta-model type of this object.

parent¶: Model that contains this object.

property root¶: The root of the tree to which this object belongs.

property template¶: The model template from which this was created.

property uri¶: Model reference locator.

class BondGraphTools.base.Port(component, index)[source]¶

Bases: object

Basic object for representing ports.

Looks and behaves like a namedtuple:: component, index = Port

Parameters

component – The owner of this port.
index – The index of this port in the component.

component¶: (PortManager) The component that this port is attached to

index¶: (int) The numerical index of this port

is_connected¶: (bool) True if this port is plugged in.

`BondGraphTools.component_manager`¶

Component Libraries.

This module takes care of the loading and management of component libraries. This library will automatically load all factory libraries upon import. Additionally libraries can be added via load_library().

Component Libraries are expected to be in json format. The structure must be:

{
    "id": The unique library id (str),
    "description": The description of this library
    "components": {
        "component_id": component dictionary,
        ...
    }
}

Each Component dictionary must be of the form:

{

}

BondGraphTools.component_manager.find(component, restrict_to=None, find_all=False, ensure_unique=False)[source]¶

Find the specified component.

Parameters

component – The component id to find.
restrict_to – list or set of library id’s to be that the search should be restricted to.
find_all – False if the function should return only the first instance of the component, True if the function should return all such instances
ensure_unique – If true, this assumes that the component id must be unique across libraries, and hence will raise an exception if this is assumption is violated.

Returns

the library id, or a list of library_id in which this component can be found.

Raises

NotImplementedError - if the component is not found. –
ValueError - if the component is assume to be unique, but is not –

BondGraphTools.component_manager.get_component(component, library='base')[source]¶

Fetch the component data for the specified component.

Parameters

component – The id of the specific component
library – The id of the library to which the component belongs

Returns

dict - the component dictionary

BondGraphTools.component_manager.get_components_list(library)[source]¶

Fetch a list of components available in the given library.

Parameters: library – The library id of the library to query
Returns: list of (component id, description) tuples

BondGraphTools.component_manager.get_library_list()[source]¶

Fetch a list of the libraries available for use.

Returns: list of (library id, description) tuples

BondGraphTools.component_manager.load_library(filename)[source]¶

Load the library specified by the filename.

Parameters: filename – The (absolute) filename of the library to be loaded.
Returns: True if the library was successfully loaded.
Return type: bool

`BondGraphTools.exceptions`¶

Exceptions and errors for BondGraphTools

exception BondGraphTools.exceptions.InvalidComponentException[source]¶: Exception for when trying to use a model that can’t be found, or is of the wrong type

exception BondGraphTools.exceptions.InvalidPortException[source]¶: Exception for trying to access a port that is in use, or does not exist

exception BondGraphTools.exceptions.ModelException[source]¶: Exception for inconsistent or invalid models when running simulations

exception BondGraphTools.exceptions.ModelParsingError[source]¶: Exception for problems generating symbolic equations from string

exception BondGraphTools.exceptions.SolverException[source]¶: Exception for issues running numerical solving.

exception BondGraphTools.exceptions.SymbolicException[source]¶: Exception for when there are issues in model reduction or symbolic manipulation

`BondGraphTools.fileio`¶

The file save/load interface and file format data model.

This module provides the basic IO functionality such as saving and loading to file.

BondGraphTools.fileio.load(file_name, model=None, as_name=None)[source]¶

Load a model from file.

Parameters: file_name (str or Path) – The file to load.
Returns: An instance of BondGraph
Raises: NotImplementedError –

BondGraphTools.fileio.save(model, filename)[source]¶

Save the model to file.

Parameters

model – The model to be saved
filename – The file to save to

`BondGraphTools.sim_tools`¶

Tools for running model simulations.

BondGraphTools.sim_tools.simulate(*args, **kwargs)[source]¶

Simulate the system dynamics.

This method integrates the dynamics of the system over the specified interval of time, starting at the specified initial state.

The solver used is a differential-algebraic integrator which respects conservation laws and algebraic constraints. It is expected that the initial state satisfies the systems inherent algebraic constrains; inconsistent initial conditions will raise exceptions.

The initial values of derivatives can be specified and the solver will ensure they are consistent with the initial state, or change them if they are not.

todo: detial control variables.

:param system BondGraph: The system to simulate :param timespan: A pair (list or tuple) containing the start and end

points of the simulation.

Parameters

x0 – The initial conditions of the system.
dx0 (Optional) – The initial rates of change of the system. The default value (None) indicates that the system should be initialised from the state variable initial conditions.
dt – The time step between reported (not integrated) values.
control_vars – A dict, list or tuple specifing the values of the control variables.

Returns

numpy array of timesteps x: numpy array of state values

Return type

t

Raises

ModelException, SolverException –

`BondGraphTools.reaction_builder`¶

A set of common tools for building and manipulating chemical reactions, and for producing bond graph models from a reaction network.

class BondGraphTools.reaction_builder.Reaction_Network(reactions=None, name=None, temperature=300, volume=1)[source]¶

Bases: object

Parameters

reactions –
name –
temperature – Temperature in Kelvin (Default 300K, or approx 27c)
volume –

add_chemostat(species, concentration=None)[source]¶

Add a (generalised) Chemostat to the reaction network. This provides a variable source of the particular species so as to maintain a particular concentration. This can also act as a I/O source.

Notes

Only one chemostat is available per species; so adding a duplicate will overwrite the previous chemostatic concentration (if defined)

Parameters

species – The name/identifier of the particular chemical species
concentration – (default None) The fixed concentration. Left as a free parameter if None

add_flowstat(species, flux=None)[source]¶

Adds a (generalised) Flowstat, which provides a flux of the particular species in or out of the reaction network.

Notes

Only one flowstat per species, so adding duplicate flowstats will overwrite the previous flowstatic fluxes (if defined)

See also

add_chemostat()

Parameters

species – The name/identifier of the chemical species
flux – (default None) The rate at which this species is added/removed. Left as a free paramter if None

add_reaction(reaction, forward_rates=None, reverse_rates=None, name='')[source]¶

Adds a new reaction to the network.

Parameters

reaction (str) – A sequence of reactions to be added.
forward_rates (list) – The forward rates of these reactions.
reverse_rates (list) – The reverse rates of these reactions.
name – The name of this set of reactions.

Reactions are assumed to be of the form:

"A + B = C + D = E + F"

Where the “math:i`th equals sign denotes a reversible reaction, with forward and reverse rates (if they exist) denoted by `forward_rate[i] and reverse_rate[i] respectively.

Warning

Rate functionality is not yet implemented!

as_network_model(normalised: bool = False)[source]¶

Produces a bond graph BondGraph.BondGraph model of the system

Parameters: normalised – If true, sets pressure and temperature to 1
Returns: A new instance of BondGraphTools.BondGraph representing this reaction system.

property fluxes¶

The reaction fluxes.

A tuple (V,x) contain the vector $V(x)$ and the coordinates :math:’x_{i}` such that for the the stoichiometric matrix $N$ and the reation rates $\kappa = ext{diag}(\kappa_1, \kappa_2, \ldots)$, the mass action description of the system is math:

\dot{x} = N\kappa V(x)

property forward_stoichiometry¶: The forward stoichiometric matrix.

name¶: The name of this reaction network

property reverse_stoichiometry¶: The reverse stoichiometric matrix.

property species¶: A list of the chemical species invoved in this reaction network

property stoichiometry¶: The stoichiometric matrix