REQUIREMENT  Proposed for review  --Dchassin 23:27, 19 June 2012 (UTC)

Controls - Controls module requirements

## Application Concept

Linear systems can be represented using standard models such that the behavior of devices and their controls is represented in a manner that is consistent with GridLAB-D's time-domain approach to simulation, while maintaining a clear connection to the methods used in control theory to design and analyze those systems. The Controls module uses these standard control models to define arbitrary linear systems using a single object. This eliminates the need to define in detail all the external components of systems that can influence a GridLAB-D and allows users to focus on the detailed agent-based behavior of specifics objects while treating other parts of the model as standard linear systems.

## Use Cases

State space model use case
A user wants to model the response of a voltage control strategy on a feeder where underfrequency load shedding is implemented. A model of an aggregate load with a frequency load control system is given as a state-space model. The frequency event is played and the aggregate load model responds. The feeder model with aggregate loads is modeled and the feeder voltage control strategy is tested for the events played.
Transfer function model use case
A user wants to model the response of a voltage control strategy on a feeder where underfrequency load shedding is implemented. A model of an aggregate load with a frequency load control system is given as a transfer function. The frequency event is played and the aggregate load model responds. The feeder model with aggregate loads is modeled and the feeder voltage control strategy is tested for the events played.
Differential model use case
A user wants to model the response of a voltage control strategy on a feeder where underfrequency load shedding is implemented. A model of an aggregate load with a frequency load control system is given as a differential model. The frequency event is played and the aggregate load model responds. The feeder model with aggregate loads is modeled and the feeder voltage control strategy is tested for the events played.

## General Requirements

### R1

Canonical form
State space models shall represent single-output systems in the canonical form
$\begin{matrix} \dot x = Ax + Bu \\ y = Cx + Du \end{matrix}$

### R1.1

State vector
The state vector $x$ shall be of dimension $N$.

### R1.2

Control vector
The control vector $u$ shall be of dimension $M$.

### R1.3

Observation variable
The observation variable $y$ shall be of dimension 1.

### R1.4

State matrix
The $A$ matrix shall be an $N \times N$ matrix and shall represent the state matrix.

### R1.5

Input matrix
The $B$ matrix shall be an $N \times M$ matrix and shall represent the input matrix.

### R1.6

Output matrix
The $C$ matrix shall be an $1 \times N$ matrix and shall represent the output matrix.

### R1.7

Feedforward matrix
The $D$ matrix shall be an $1 \times M$ matrix and shall represent the feedforward matrix.

### R1.8

The state vector $x$, the input vector $u$, and the output variable $y$ shall be linked to properties of objects.

### R1.8.1

Hidden states
Values in the state vector $x$ may be "hidden", in which case they shall be allocated and initialized when the state space model is constructed.

### R2

Transfer function
Transfer functions shall be represented in the form $H(s) = Y(s) / U(s)$.

### R2.1

Output function
The $Y$ function shall be the numerator of the transfer function and shall represent the output function.

### R2.2

Input function
The $U$ function shall be the denominator of the transfer function and shall represent the input function.

### R3

Differential form
Differential equations shall be represented in the form $a_1 \dot q + a_2 \ddot q + \cdots + a_n d^nq/dt^n = b_0 u$

### R4

Timestep
The time step of the state space model shall be defined by the user.

### R5

Controllable and observable forms
The canonical form the of the state space model shall be either controllable or observable.

### R6

Alternate definitions
The user shall be required to specify either the transfer function (i.e., using $Y$ and $U$), the diffential form (i.e., using $q$) or the state space model (i.e., using $A$, $B$, $C$, and $D$).

### R6.1

Conversion from transfer function
When the transfer function is specified, the state space model shall be generated at initialization based on the canonical form chosen by the user.

### R6.2

Conversion from differential form
When the differential model is specified, the state space model shall be generated at initialization based on the canonical form chosen by the user.

### R6.3

Conversion from state space form
When the state space form is update, the transfer function description (Y and U) and the differential form (q) shall be updated automatically.

### R7

Switched systems
When the transfer function or the state space model is changed, the model shall be updated to remain consistent with the change.

### R7.1

System mode
Switched system models shall be supported using a mode parameter.

### R7.2

Mode syntax
The transfer function and state space properties syntax shall allow for the definition of switched systems based on the mode.

### R7.3

Mode reference
The user shall specify the mode either as a property of the model or a reference to an integer or enumeration property of another object.