# Getting Started

This example runs through the basic steps of building and simulating a bond graph model. For a full list of functions refer to the API Reference.

Our first example will be a simple electric circuit of a capacitor, resistor, and current supply in parallel. We will first model this circuit without the current supply.

## Bond graph construction

We first create a `BondGraph`

object which will hold all our components. This is an empty object that will soon be populated with components and bonds.

`model = BondGraph("RC Circuit")`

`BondGraph RC Circuit (0 Nodes, 0 Bonds)`

Next we will create a capacitor as a bond graph 'C'-component. The component type's `description`

can be printed for extra information.

```
C = Component(:C)
description(:C)
```

```
Generalised Linear Capacitor
e = (1/C)*q
dq/dt = f
C: Capacitance [1.0]
q: Generalised position [0.0]
```

Available component types are defined in `BondGraphs.DEFAULT_LIBRARY`

. The default component types are:

- Standard components (
`:C`

,`:R`

,`:I`

,`:TF`

) - Biochemical components (
`:Ce`

,`:Re`

,`:ce`

,`:re`

) - Sources of effort or flow (
`:Se`

,`:Sf`

,`:SCe`

)

We next create a resistor 'R'-component and an `EqualEffort`

node which represents Kirchoff's Voltage Law. In bond graph terminology, 0-Junctions are `EqualEffort`

nodes, and 1-Junctions are `EqualFlow`

nodes.

```
R = Component(:R)
kvl = EqualEffort()
```

`𝟎`

Components and nodes are added to the model, and connected together as a graph network. Note that components must first be added to the model before they can be connected.

```
add_node!(model, [C, R, kvl])
connect!(model, R, kvl)
connect!(model, C, kvl)
model
```

`BondGraph RC Circuit (3 Nodes, 2 Bonds)`

Because our bond graph is fundamentally a graph, we can using existing graph methods on our model.

```
using Graphs
incidence_matrix(model)
```

```
3×2 SparseArrays.SparseMatrixCSC{Int64, Int64} with 4 stored entries:
⋅ -1
-1 ⋅
1 1
```

We can also visualise our model structure by plotting it as a graph network using Plots.jl.

```
using Plots
plot(model)
```

## Simulating our model

With a bond graph we can automatically generate a series of differential equations which combine all the constitutive relations from the components, with efforts and flows shared according to the graph structure.

`constitutive_relations(model)`

\[ \begin{align} \frac{\mathrm{d} C_{+}q\left( t \right)}{\mathrm{d}t} =& \frac{ - C_{+}q\left( t \right)}{C_{+}C R_{+}R} \end{align} \]

We will set values for the component parameters in the model. Each component comes with default values. When substituted into our equations, we get the following relation for the capacitor charge `C.q(t)`

.

```
C.C = 1
R.R = 2
constitutive_relations(model; sub_defaults=true)
```

\[ \begin{align} \frac{\mathrm{d} C_{+}q\left( t \right)}{\mathrm{d}t} =& \frac{ - C_{+}q\left( t \right)}{2} \end{align} \]

We can solve this bond graph directly using the in-built `simulate`

function.

```
tspan = (0., 10.)
u0 = [1] # initial value for C.q(t)
sol = simulate(model, tspan; u0)
plot(sol)
```

Under the hood, our `simulate`

function is converting our bond graph into an `ModelingToolkit.ODESystem`

. We can chose instead to create an `ODESystem`

directly and handle it with whatever functions we like.

## Adding control variables

We will expand our model by adding an external current (flow) supply in parallel, represented by the component `Sf`

(Source of Flow)

```
Is = Component(:Sf, "Is")
add_node!(model, Is)
connect!(model, Is, kvl)
plot(model)
```

We will add a the forcing function `fs(t) = sin(2t)`

as an external current input.

```
Is.fs = t -> sin(2t)
constitutive_relations(model; sub_defaults=true)
```

\[ \begin{align} \frac{\mathrm{d} C_{+}q\left( t \right)}{\mathrm{d}t} =& \frac{ - C_{+}q\left( t \right) + 2 \sin\left( 2 t \right)}{2} \end{align} \]

```
sol = simulate(model, tspan; u0)
plot(sol)
```

The input can be any arbitrary julia function of t, so long as it returns a sensible output. Note that for this to work you must register the custom function with `@register_symbolic`

, so that the library knows not to simplify this function further.

```
using ModelingToolkit
@register_symbolic f(t)
Is.fs = t -> f(t)
f(t) = t % 2 <= 1 ? 0 : 1 # repeating square wave
sol = simulate(model, tspan; u0)
plot(sol)
```