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

- [math]\begin{matrix} \dot x = Ax + Bu \\ y = Cx + Du \end{matrix} [/math]

### R1.1

- State vector
- The state vector [math]x[/math] shall be of dimension [math]N[/math].

### R1.2

- Control vector
- The control vector [math]u[/math] shall be of dimension [math]M[/math].

### R1.3

- Observation variable
- The observation variable [math]y[/math] shall be of dimension 1.

### R1.4

- State matrix
- The [math]A[/math] matrix shall be an [math]N \times N[/math] matrix and shall represent the state matrix.

### R1.5

- Input matrix
- The [math]B[/math] matrix shall be an [math]N \times M[/math] matrix and shall represent the input matrix.

### R1.6

- Output matrix
- The [math]C[/math] matrix shall be an [math]1 \times N[/math] matrix and shall represent the output matrix.

### R1.7

- Feedforward matrix
- The [math]D[/math] matrix shall be an [math]1 \times M[/math] matrix and shall represent the feedforward matrix.

### R1.8

- Object property links
- The state vector [math]x[/math], the input vector [math]u[/math], and the output variable [math]y[/math] shall be linked to properties of objects.

### R1.8.1

- Hidden states
- Values in the state vector [math]x[/math] 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 [math]H(s) = Y(s) / U(s)[/math].

### R2.1

- Output function
- The [math]Y[/math] function shall be the numerator of the transfer function and shall represent the output function.

### R2.2

- Input function
- The [math]U[/math] 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 [math]a_1 \dot q + a_2 \ddot q + \cdots + a_n d^nq/dt^n = b_0 u[/math]

### 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 [math]Y[/math] and [math]U[/math]), the diffential form (i.e., using [math]q[/math]) or the state space model (i.e., using [math]A[/math], [math]B[/math], [math]C[/math], and [math]D[/math]).

### 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.