Merge pull request #11 from martinjrobins:i9-docs

#9 more docs

book/src/SUMMARY.md

@@ -1,4 +1,7 @@
 # Summary
 
-- [Introduction](../../README.md)
-- [DiffSL Language](./language.md)
+- [DiffSL Language](./introduction.md)
+- [Tensor Variables](./tensors.md)
+- [Tensor Operations](./operations.md)
+- [Defining ODEs](./odes.md)
+- [Inputs and Outputs](./inputs_outputs.md)

book/src/inputs_outputs.md

@@ -0,0 +1,69 @@
+# Inputs & Outputs
+
+Often it is useful to parameterize the system of equations using a set of input parameters. It is also useful to be able to extract certain variables from the system for further analysis. 
+In this section we will show how to specify inputs and outputs in the DiffSL language.
+
+## Specifying inputs
+
+We can override the values of any scalar variables by specifying them as input
+variables.  To do this, we add a line at the top of the code to specify that
+these are input variables:
+
+```
+in = [k]
+k { 1.0 }
+u { 0.1 }
+F { k * u }
+```
+
+Here we have specified a single input parameter `k` that is used in the RHS function `F`. 
+The value of `k` is set to `1.0` in the code, but this value is only a default, and can be overridden by passing in a value at solve time.
+
+We can use input parameters anywhere in the code, including in the definition of other input parameters.
+
+```
+in = [k]
+k { 1.0 }
+g { 2 * k }
+F { g * u }
+```
+
+or in the intial conditions of the state variables:
+
+```
+in = [k]
+k { 1.0 }
+u_i {
+  x = k,
+}
+F { u }
+```
+
+
+## Specifying outputs
+
+We can also specify the outputs of the system. These might be the state
+variables themselves, or they might be other variables that are calculated from
+the state variables. 
+
+Here is an example where we simply output the elements of the state vector:
+
+```
+u_i {
+  x = 1.0,
+  y = 2.0,
+  z = 3.0,
+}
+out_i { x, y, z }
+```
+
+or we can derive additional outputs from the state variables:
+
+```
+u_i {
+  x = 1.0,
+  y = 2.0,
+  z = 3.0,
+}
+out { x + y + z }
+```

book/src/introduction.md

@@ -0,0 +1,47 @@
+DiffSL Language
+
+The DSL is designed to be an easy and flexible language for specifying
+DAE systems and is based on the idea that a DAE system can be specified by a set
+of equations of the form:
+
+$$
+M(t) \frac{d\mathbf{u}}{dt} = F(\mathbf{u}, t)
+$$
+
+where \\( \mathbf{u}$ \\) is the vector of state variables and \\( t \\) is the time. The DSL
+allows the user to specify the state vector \\( \mathbf{u} \\) and the RHS function \\( F \\).
+Optionally, the user can also define the derivative of the state vector \\( d\mathbf{u}/dt \\)
+and the mass matrix \\( M \\) as a function of \\( d\mathbf{u}/dt \\) (note that this function should be linear!).
+
+The user is also free to define an an arbitrary number of intermediate
+scalars and vectors of the users that are required to calculate \\( F \\) and \\( M \\).
+
+## A Simple Example
+
+To illustrate the language, consider the following simple example of a logistic growth model:
+
+$$
+\frac{dN}{dt} = r N (1 - N/K)
+$$
+
+where \\( N \\) is the population, \\( r \\) is the growth rate, and \\( K \\) is the carrying capacity.
+
+To specify this model in DiffSL, we can write:
+
+``
+in = [r, k]
+u_i {
+  N = 0.0
+}
+F_i {
+  r * N * (1 - N/k)
+}
+out_i {
+  N
+}
+``
+
+Here, we define the input parameters for our model as a vector `in` with the growth rate `r` and the carrying capacity `k`. We then define the state vector `u_i` with the population `N` initialized to `0.0`. Next, we define the RHS function `F_i` as the logistic growth equation. Finally, we define the output vector `out_i` with the population `N`.
+
+
+