# Reference

`BondGraphs.Bond`

`BondGraphs.BondGraph`

`BondGraphs.BondGraph`

`BondGraphs.BondGraphNode`

`BondGraphs.Component`

`BondGraphs.EqualEffort`

`BondGraphs.EqualFlow`

`BondGraphs.SourceSensor`

`BondGraphs.add_node!`

`BondGraphs.addlibrary!`

`BondGraphs.connect!`

`BondGraphs.constitutive_relations`

`BondGraphs.constitutive_relations`

`BondGraphs.description`

`BondGraphs.disconnect!`

`BondGraphs.getbonds`

`BondGraphs.getnodes`

`BondGraphs.insert_node!`

`BondGraphs.merge_nodes!`

`BondGraphs.remove_node!`

`BondGraphs.simplify_junctions!`

`BondGraphs.simulate`

`BondGraphs.swap!`

## Types

`BondGraphs.Bond`

— Type```
Bond(source::AbstractNode, destination::AbstractNode)
Bond((source_node, port_label), (destination_node, port_label))
```

Connect two bond graph components (or two ports of two components) with a bond. The bond direction is from `source`

to `destination`

. If the ports are not specified, the bond will be created between the next available ports in each component.

In most cases it is better to use `connect!`

instead.

`BondGraphs.BondGraph`

— Type```
BondGraph(name="BG") <: Graphs.AbstractGraph{Int64}
BondGraph(name, nodes::Vector{AbstractNode}, bonds::Vector{Bond})
```

The bond graph object which contains a vector of `nodes`

and `bonds`

. All operations on components or bonds must happen within the same bond graph. This inherits the methods of the AbstractGraph type and so will work with

See also `BondGraphNode`

.

`BondGraphs.BondGraph`

— Method`BondGraph(rs::ReactionSystem; chemostats=[])`

Convert a Catalyst.ReactionSystem into a BondGraph.

`chemostats`

are chemical species with fixed concentrations. In bond graph terms, these are "SCe" types (chemical energy sources) instead of "Ce" types (chemical energy store).

`BondGraphs.BondGraphNode`

— Type`BondGraphNode(bg::BondGraph, name=name(bg); deep_copy=false)`

Convert a `BondGraph`

into a component that can be added in another level bond graph. Componets can be exposed to the outer bond graph by replacing them with a `SourceSensor`

type using the `swap!`

function.

See also `BondGraph`

.

`BondGraphs.Component`

— Type```
Component{N} <: AbstractNode
Component(type, name=type)
Component(type, name=type; library=BondGraphs.DEFAULT_LIBRARY, <keyword arguments>)
```

Construct a Component of a defined (bondgraph) type ∈ {R, C, I, Se, Sf, TF, Ce, Re, SCe}.

Components have a `N`

fixed ports when generated. This is usually determined by the bond graph type. Other properties and equations of available components are defined in `BondGraphs.DEFAULT_LIBRARY`

(see `description`

).

`BondGraphs.EqualEffort`

— Type`EqualEffort <: Junction`

Efforts are all equal, flows sum to zero (0-junction). Has an unlimited number of ports.

`BondGraphs.EqualFlow`

— Type`EqualFlow <: Junction`

Flows are all equal, efforts sum to zero (1-junction). Has an unlimited number of ports.

`BondGraphs.SourceSensor`

— Type`SourceSensor <: AbstractNode`

Special component type that acts as a source of both effort and flow. SourceSensors are used as external ports for `BondGraphNode`

s.

## Methods

`BondGraphs.add_node!`

— Method`add_node!(bg::BondGraph, nodes)`

Add a node to a bond graph `bg`

. Can add a single node or list of nodes.

`BondGraphs.addlibrary!`

— Method`addlibrary!(newlib)`

Combine the library `newlib`

with the default library used within BondGraphs. `newlib`

will need to be in the form of a dictionary, and new components should follow the below schema.

NOTE: This library is likely to change in the future. Do not rely on this schema too much.

**Library Schema**

- description -> written description of the component and definitions
- numports -> the number of ports in the component
- variables ->
- parameters -> constant parameters, unique for each component instance
- globals -> global parameters (i.e. no namespace)
- states -> time-dependent state variables
- controls -> time-dependent parameters that can accept julia functions

- equations -> symbolic description of the constitutive equations

`BondGraphs.connect!`

— Method```
connect!(bg::BondGraph, source_node, destination_node)
connect!(bg::BondGraph, (source_node, port_label), (destination_node, port_label))
```

Connect two components together in the same bond graph. The bond direction is always from `source_node`

to `destination_node`

. The port index of `source_node`

and `destination_node`

can be optionally set.

`BondGraphs.constitutive_relations`

— Method`constitutive_relations(n::AbstractNode)`

Return the constitutive relations (equations) for node `n`

.

If `n`

is a Junction, the flow and effort constraints are generated from its connections.

`BondGraphs.constitutive_relations`

— Method`constitutive_relations(bg::BondGraph; sub_defaults=false)`

Generate the constitutive relations (equations) for bond graph `bg`

.

The equations are symbolically derived from the equations of all the nodes and bonds in the bond graph. If `sub_defaults`

is true, the default parameter values for each component are subbed into the equations.

NOTE: This creates a ModelingToolkit.ODESystem of the bond graph and returns only the equations. If you want to numerically solve the bond graph equations, either use `simulate`

or create an ODESystem directly.

`BondGraphs.description`

— Method```
description(comp::Symbol)
description(lib, comp::Symbol)
```

Print the description of the component with symbol `comp`

in library `lib`

.

`BondGraphs.disconnect!`

— Method`disconnect!(bg::BondGraph, node1, node2)`

Remove the bond connecting `node1`

and `node2`

. The order of nodes does not matter.

`BondGraphs.getbonds`

— Method```
getbonds(bg::BondGraph, n1::AbstractNode, n2::AbstractNode)
getbonds(bg::BondGraph, (n1, n2))
```

Return the bond in `bg`

connecting nodes `n1`

and `n2`

, if it exists.

`BondGraphs.getnodes`

— Method`getnodes(bg::BondGraph, type)`

Return all nodes a particular bond graph type in the bond graph `bg`

.

`type`

can be a DataType (e.g. Component{1}), a string (e.g. "C"), or a vector of strings.

`BondGraphs.insert_node!`

— Method```
insert_node!(bg::BondGraph, bond, newnode)
insert_node!(bg::BondGraph, (node1, node2), newnode)
```

Inserts `newnode`

between two existing connected nodes. The direction of the original bond is preserved.

Supply either the two nodes as a tuple, or the bond that connects them in `bg`

.

`BondGraphs.merge_nodes!`

— Method`merge_nodes!(bg::BondGraph, node1, node2; junction=EqualEffort())`

Combine two copies of the same component in `bg`

by adding a `junction`

and connecting the neighbours of `node1`

and `node2`

to the new junction.

Merging nodes this way means there is only one component representing a system element, and all other nodes connect to the component via the new junction.

`BondGraphs.remove_node!`

— Method`remove_node!(bg::BondGraph, nodes)`

Remove a node to a bond graph `bg`

. Can remove a single node or list of nodes.

`BondGraphs.simplify_junctions!`

— Method`simplify_junctions!(bg::BondGraph; remove_redundant=true, squash_identical=true)`

Remove unnecessary or redundant Junctions from bond graph `bg`

.

If `remove_redundant`

is true, junctions that have zero or one neighbours are removed, and junctions with two neighbours are squashed (connected components remain connected).

If `squash_identical`

is true, connected junctions of the same type are squashed into a single junction.

`BondGraphs.simulate`

— Method`simulate(bg::BondGraph, tspan; u0=[], pmap=[], solver=Tsit5(), flag_ODE=true, kwargs...)`

Simulate the bond graph model.

The keyword arguments are the same as for `ODEProblem`

and `solve`

in DifferentialEquations.

`BondGraphs.swap!`

— Method`swap!(bg::BondGraph, oldnode, newnode)`

Remove `oldnode`

from bond graph `bg`

and replace it with `newnode`

. The new node will have the same connections (bonds) as the original model.

`newnode`

must have a greater or equal number of ports as `oldnode`

.