part modify equation linear_state_equation
Allows you to modify an existing linear_state_equation.
The equation command allows you to create and manage equation elements in your model. These elements include differential_equations, transfer_functions, linear_state_equations, and general_state_equations. EQUATIONS help you model controls system elements or any other phenomena that can be represented by differential equations. Adams View makes it easier for you to identify these equations by allowing you to assign them names and drawing them as icons on the screen. During preprocessing, the icons for the EQUATIONs you create are displayed at or near the origin of your model by Adams View. All EQUATIONs are "owned" by a particular model and then you reference these EQUATIONs in the definition of other model objects.
The LINEAR_STATE_EQUATION is used, along with associated arrays and matrices statements, to define a system of constant coefficient, explicit, differential, and algebraic equations in the classic state-space format. The Linear State Equation (LSE) is designed to model a linear, time-invariant control system defined in the state space, especially to facilitate importation of controllers developed in with external software. It can be used, however, to define any arbitrary set of coupled constant-coefficient differential and algebraic equations which can be expressed in matrix notation as:
| dX/dt | | A | B | | X |
< ----- > = | ----- | < - >
| Y | | C | C | | U |
\ / - - \ /
where at least the A matrix must be non-zero. The LINEAR_STATE_EQUATION follows standard control systems terminology, where X is the state vector, Y is the output vector, U is the input vector and IC is the initial condition vector, X(t = 0). In the Adams data set, each of these vectors is defined using an ARRAY. Similarly, A is the state matrix, B is the control matrix, C is the output matrix, and D is the feed-forward matrix. Each of these matrices is defined using a MATRIX. All MATRIX and ARRAY sizes must be conformable as required by the above equation. ARRAYs with zero-length and zero-sized matrices should not be defined; Adams will correctly formulate the system equations based on those ARRAYs and MATRIXs which do exist.
Format:
part modify equation linear_state_equation |
|---|
linear_state_equation_name= | an existing lse |
new_linear_state_equation_name= | a new lse |
adams_id= | integer |
comments = | string |
x_state_array_name = | an existing array |
u_input_array_name = | an existing array |
y_output_array_name = | an existing array |
ic_array_name = | an existing array |
a_state_matrix_name = | an existing matrix |
b_input_matrix_name = | an existing matrix |
c_output_matrix_name = | an existing matrix |
d_feedforward_matrix_name = | an existing matrix |
static_hold = | on_off |
Example:
part modify equation linear_state_equation & |
|---|
linear_state_equation_name = | .model_1.lse_1 & |
new_linear_state_equation_name = | new_eq & |
adams_id = | 1 & |
comments = | lse_of_part_2 & |
x_state_array_name = | .model_1.array_11 & |
u_input_array_name = | .model_1.array_7 & |
y_output_array_name = | .model_1.array_12 & |
ic_array_name = | .model_1.array_15 & |
a_state_matrix_name = | .model_1.a & |
b_input_matrix_name = | .model_1.b & |
c_output_matrix_name = | .model_1.c & |
d_feedforward_matrix_name = | .model_1.d & |
static_hold = | on |
Description:
Parameter | Value Type | Description |
|---|
linear_state_equation_name | An Existing Lse | Specifies the linear state equation to modify |
new_linear_state_equation_name | A New Lse | Specifies the name of a new linear state equation |
adams_id | Integer | Specifies a integer used to identify this element in Adams data file |
comments | String | Specifies the comments about the object being created or modified |
x_state_array_name | An Existing Array | Specifies the array to represent the state array |
u_input_array_name | An Existing Array | Specifies an array to be used as input or control of linear system |
y_output_array_name | An Existing Array | Specifies an array name to be used as output array |
ic_array_name | An Existing Array | Specifies the array name for stating the initial conditions of linear system |
a_state_matrix_name | An Existing Matrix | Specifies the array to be used as state matrix |
b_input_matrix_name | An Existing Matrix | Specifies the matrix to be used as control matrix |
c_output_matrix_name | An Existing Matrix | Specifies the matrix to be used as output matrix |
d_feedforward_matrix_name | An Existing Matrix | Specifies the feed-forward matrix name of the linear system |
static_hold | On_off | Indicates that the equations states are not changed during static and quasi-static analysis |
Extended Definition:
1. Specifies the linear_state_equation to modify. You use this parameter to identify the existing linear_state_equation to affect with this command. You may identify a linear_state_equation by typing its name or by picking it from the screen. Since linear_state_equations do not have a geometric position, Adams View displays linear_state_equation icons at or near the model origin. If the linear_state_equation icon is not visible on the screen, you must type the name. You may also find it convenient to type the name even if the linear_state_equation icon is displayed. If you created the linear_state_equation by reading an Adams data set or graphics file, the linear_state_equation name is the letters LSE followed by the Adams data set linear_state_equation ID number. The name of Adams LSE/101 is LSE101, for example. If you created the linear_state_equation during preprocessing, you gave it a name at that time. If a linear_state_equation is owned by the default model, you may identify it by entering its name only. If it is not, you must enter its full name. To identify a linear_state_equation under a different model, for instance, you may need to enter the model name as well. For example, you may specify linear_state_equation 'fluid_volume' from model 'hydro' by entering ".hydro.fluid_volume'". If you type a "?", Adams View will list the linear_state_equation available by default. You must separate multiple linear_state_equation names by commas. If the linear_state_equation is visible in one of your views, you may identify it by picking on any of the graphics associated with it. You need not separate multiple linear_state_equation picks by commas.
2. The new name specifies the name of the new linear_state_equation. You may use this name later to refer to this linear_state_equation. Adams View will not allow you to have two linear_state_equations with the same full name, so you must provide a unique name. Normally, entity names are composed of alphabetic, numeric, or '_' (underscore) characters, and start with an alphabetic or '_' character. They may be any length. For more information, see
Using Extended Names. By enclosing the name in double quotes, you may use other printable characters, or start the name with a numeral. If a name contains characters, or starts with a numeral, you must always quote the name when entering it. Note that you can specify the parentage of an entity (e.g. what part "owns" a marker or a geometry element) when you CREATE it by changing the name. If you enter just the entity name, then the default parent will be assigned by Adams View. If you type in the full name, then you may over ride the default parent. In most cases, when creating an entity, Adams View will provide a default name. The default name that Adams View provides will specify the parentage that it has assumed. You may, or course, delete this name and use your own. The form of a full name is:
"...._NAME.GRAND_PARENT_NAME.PARENT_NAME.ENTITY_NAME"
The number of levels used varies from case to case and the parentage must exist before an entity can be assigned to it
3. Adams id specifies an integer used to identify this element in the Adams data file. When you use the FILE ADAMS_DATA_SET WRITE command, Adams View writes an Adams data file for your model. Adams requires that each modeling element be identified by a unique integer identifier. If you use this parameter to specify a non-zero identifier, Adams View will use it in the corresponding statement in the Adams data file. You may also enter zero as an identifier, either explicitly or by default. The next time you write an Adams file, Adams View will replace the zero with a unique, internally-generated identifier. Adams View will permanently store this identifier with the element just as if you had entered it yourself. Normally, you would let all identifiers default to zero, and Adams View would generate the identifiers for you. You are never required to enter a non-zero identifier. You only need to specify it, if, for some reason, you wish to control the Adams file output. The value range is 0 to 99999999.
4. ‘Comments’ specifies comments for the object being created or modified. When an Adams Solver data file (.adm) is read into Adams View, all comments associated with a statement (from the end of the previous statement through the end of the current statement) are stored with the object. Comments in the data file can be associated with model. These comments must follow the title statement and be followed by the comment 'END OF MODEL COMMENTS'. This string must be uppercase. When an AdamsAdamsAdams Solver data file is written, the comments for an object are written before the statement corresponding to the object.
5. The ‘X_state array name ’ specifies the array in the model which will be used as the state array for this linear system. The user must have an array with this name in their model and it may not be used in any other LINEAR_STATE_EQUATION, GENERAL_STATE_EQUATION or TRANSFER_FUNCTION.
6. The ‘U_input array’ specifies the array name in the current model which will be used as the input (or control) array for this linear system (LINEAR_STATE_EQUATION). The use of this parameter is optional. When the U_INPUT_ARRAY_NAME parameter is used, the user must have an array with this name in their model, and it must be of the U type. When U_INPUT_ARRAY_NAME is used, the user must also include a B_INPUT_MATRIX or D_FEEDFORWARD_MATRIX name, or both, in the LINEAR_STATE_EQUATION definition, and these matrix name(s) must have the same number of columns as there are elements in the U_INPUT_ARRAY.
7. The ‘Y output array name ’ specifies the array name in your model which will be used as the output array for this linear system (LINEAR_STATE_EQUATION). When the Y_OUTPUT_ARRAY_NAME parameter is used, the user must have an array with this name in the model and it may not be used in any other LINEAR_STATE_EQUATION, GENERAL_STATE_EQUATION or TRANSFER_FUNCTION. When the Y_OUTPUT_ARRAY_NAME parameter is used, the user must also include a C_OUTPUT_MATRIX or D_FEEDFORWARD_MATRIX name, or both, in the LINEAR_STATE_EQUATION definition, and these matrices must have the same number of rows as there are elements in the Y_OUTPUT_ARRAY_NAME
8. The ‘ic array name’ specifies the array in the model which will be used as the initial conditions array for this linear system (LINEAR_STATE_EQUATION). When the IC_ARRAY_NAME parameter is used, the user must have an array with this name in their model and it must have the same number of elements as the X_STATE_ARRAY (equal to the number of rows in the A_STATE_MATRIX). When no IC array is specified for a LINEAR_STATE_EQUATION, all states are initialized to zero.
9. The ‘A state matrix name’ specifies the matrix in the model which is used as the state matrix for this linear system (LINEAR_STATE_EQUATION). The user must have a MATRIX with this name in their model, it must be a square matrix (same number of rows and columns) and it must have the same dimension as the X_STATE_ARRAY. If the user has specified an inconsistent size for the X_STATE_ARRAY, Adams will issue a warning message and automatically resizes the X_STATE_ARRAY to match the A_STATE_MATRIX.
10. The ‘B input matrix name’ specifies the matrix in the model which is used as the control matrix for this linear system (LINEAR_STATE_EQUATION). When the B_INPUT_MATRIX_NAME parameter is used, the user must also include a U_INPUT_ARRAY_NAME parameter in the LINEAR_STATE_EQUATION definition. You must have a matrix with this name in your model. This matrix must have the same number of rows as the A_STATE_MATRIX and the same number of columns as the number of elements in the U_INPUT_ARRAY
11. The ‘C output matrix name specifies the matrix in the model which is used as the output matrix for this linear system (LINEAR_STATE_EQUATION). When the C_OUTPUT_MATRIX parameter is used, you must also include a Y_OUTPUT_ARRAY parameter in the LINEAR_STATE_EQUATION definition. You must have a matrix with this name in your model. This matrix must have the same number of columns as the A_STATE_MATRIX and the same number of rows as the number of elements in the Y_OUTPUT_ARRAY.
12. The ‘D feedforward matrix name’ specifies the matrix in your model which is used as the feedforward matrix for this linear system (LINEAR_STATE_EQUATION). When the D_FEEDFORWARD_MATRIX_NAME parameter is used, you must also include both Y_OUTPUT_ARRAY_NAME and U_INPUT_ARRAY_NAME parameters in the LINEAR_STATE_EQUATION definition. You must have a matrix with this name in your model. This matrix must have the same number of rows as the number of elements in the Y_OUTPUT_ARRAY and the same number of columns as the number of elements in the U_INPUT_ARRAY.
13. The ‘static-hold’ indicates that equation states are not permitted to change during static and quasi-static analysis. The user specified initial conditions are retained as the static equilibrium values. Note that this does not guarantee that the time derivatives of the user-defined variable will be zero after static analysis.