# PROPT functions for setting upp an ODE

The following functions are usually needed for setting up an ordinary differential equation (ODE) or a differential algebraic equation (DAE).

#### collocate - Expand a propt tomSym to all collocation points on a phase.

y = collocate(phase, x) for a m-by-n tomSym object x, on a phase with p collocation points, returns an p-by-m*n tomSym with values of x for each collocation point.

If x is a cell array of tomSym objects, then collocate is applied recursively to each element in the array. See also: atPoints

#### tomSym/dot

Shortcut to overdot (alternatively dot product).

dot(p,x) gives the time derivative of x in the phase p.

dot(x) can be used to the same effect, if setPhase(p) has been called previously.

#### final - Evaluate a propt tomSym at the final point of a phase.=

y = final(phase, x) for tomSym object x, returns an object of the same size as x, where the independent variable (usually t) has been replaced by its final value on the phase.

#### icollocate - Expand a propt tomSym to all interpolation points on a phase

`y = icollocate(phase, x)` is the same as y = collocate(phase, x), except that the interpolation points are used instead of the collocation points. This is typically useful when constructing an initial guess.

#### initial - Evaluate a propt tomSym at the initial point of a phase.

y = initial(phase, x) for tomSym object x, returns an object of the same size as x, where the independent variable (usually t) has been replaced by its initial value on the phase (often 0).

If x is a cell array of tomSym objects, then initial is applied recursively to each element in the array. See also: final, subs, collocate, atPoints

#### integrate - Evaluate the integral of an expression in a phase.

y = integrate(phase, x) for tomSym object x, returns an object which has the same size as x and is the integral of x in the given phase.

#### mcollocate - Expand to all collocation points, endpoints and midpoints on a phase.

y = mcollocate(phase, x) for a m-by-n tomSym object x, on a phase with p collocation points, returns an (2p+1)-by-m*n tomSym with values of x for each collocation point, the endpoints and all points that lie halfway inbetween these points.

The mcollocate function is useful in setting up inequalities that involve state variables. Because twice as many points are used, compared to collocate, the resulting problem is slightly slower to solve, but the obtained solution is often more correct, because overshoots in between collocation points are smaller.

Because it uses many more points than there are degrees of freedom, mcollocate should only be used for inequalities. Applying mcollocate to equalities will generally result in an optimization problem that has no solution. Care should also be taken to ensure that the mcollocated condition is not in conflict with any initial or final condition.

If x is a cell array of tomSym objects, then mcollocate is applied recursively to each element in the array.

If a finite element method is used, then mcollocate uses all points that are used in computing the numeric quadrature over elements.

#### setPhase - Set the active phase when modeling PROPT problem.

setPhase(p) sets the active phase to p.

It is not strictly necessary to use this command, but when doing so, it is possible to omit the phase argument to the commands tomState, tomControl, initial, final, integrate, etc.

#### tomControl - Generate a PROPT symbolic state.

``` x = tomControl creates a scalar PROPT control with an automatic name.
x = tomControl(phase,label) creates a scalar control with the provided name.
x = tomControl(phase,label,m,n) creates a m-by-n matrix of controls.
x = tomControl(phase,[],m,n) creates a matrix control with an automatic name.
x = tomControl(phase,label,m,n,'int') creates an integer matrix symbol.
x = tomControl(phase,label,m,n,'symmetric') creates a symmetric matrix symbol.
```

The tomControl symbols are different from tomState symbols in that the states are assumed to be continuous, but not the controls. This means that derivatives of tomControls should typically not be used in the differential equations, and no initial or final condition should be imposed on a tomControl.

If setPhase has been used previously, then the phase is stored in a global variable, and the phase argument can be omitted.

Constructs like "x = tomControl('x')" are very common. There is the shorthand notation "tomControls x". See also: tomControls, tomState, tom

#### tomControls - Create tomControl objects

Examples:

```   tomControls x y z
```

is equivalent to

```x = tomControl('x');
y = tomControl('y');
z = tomControl('z');

tomControls 2x3 Q 3x3 -integer R -symmetric S
```

is equivalent to

```Q  = tomControl('Q', 2,  3);
R  = tomControl('R', 3,  3,  'integer');
S  = tomControl('S', 3,  3,  'integer', 'symmetric');
```

Note: While the "tomControls" shorthand is very convenient to use prototyping code, it is recommended to only use the longhand "tomControl" notation for production code. (See toms for the reason why.)

It is necessary to call setPhase before calling tomStates.

#### tomPhase - Create a phase struct

phase = tomPhase(label, t, tstart, tdelta, ipoints, cpoints) The ipoints (interpolation points) and cpoints (collocation points) input arguments must be vectors of unique sorted points on the interval 0 to 1.

phase = tomPhase(label, t, tstart, tdelta, n) automatically creates cpoints and ipoints using n Gauss points. (If n > 128 then Chebyshev points are used instead.)

phase = tomPhase(label, t, tstart, tdelta, n, [], 'cheb') uses Chebyshev points instead of Gauss points. This yields better convergence for some problems, and worse for others, as compared to Gauss points.

#### tomState - Generate a PROPT symbolic state

```x = tomState creates a scalar PROPT state with an automatic name.
x = tomState(phase,label) creates a scalar state with the provided name.
x = tomState(phase,label,m,n) creates a m-by-n matrix state.
x = tomState(phase,[],m,n) creates a matrix state with an automatic name.
x = tomState(phase,label,m,n,'int') creates an integer matrix symbol.
x = tomState(phase,label,m,n,'symmetric') creates a symmetric matrix symbol.
```

The tomState symbols are different from tomControl symbols in that the states are assumed to be continuous. This means that they have time derivatives, accessible via the dot() function, and that tomStates cannot be integers.

If setPhase has been used previously, then the phase is stored in a global variable, and the phase argument can be omitted.

Constructs like "x = tomState('x')" are very common. There is the shorthand notation "tomStates x". See also: tomStates, tom, tomControl, setPhase

#### tomStates - Create tomState objects as toms create tomSym objects

Examples:

```tomStates  x y z
```

is equivalent to

```   x = tomState('x');
y = tomState('y');
z = tomState('z');
```

tomStates 2x3 Q 3x3 R -symmetric S is equivalent to

```Q  = tomState('Q', 2,  3);
R  = tomState('R', 3,  3);
S  = tomState('S', 3,  3,  'symmetric')
```
```   tomStates 2x3 Q 3x3 R -symmetric S
is equivalent to
Q = tomState('Q', 2, 3);
R = tomState('R', 3, 3);
S = tomState('S', 3, 3, 'symmetric')
```
```   tomStates 3x1! v
is equivalent to
v1 = tomState('v1');
v2 = tomState('v2');
v3 = tomState('v3');
v = [v1;v2;v3];
```

See the help for "toms" for more info on how to use the different flags.

Note: While the "tomStates" shorthand is very convenient to use prototyping code, it is recommended to only use the longhand "tomState" notation for production code. (See toms for the reason why.)

It is necessary to call setPhase before calling tomStates.