part modify equation general_state_equation
Allows you to modify an existing general_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.
A GENERAL_STATE_EQUATION is used along with associated ARRAYs and user-subroutines to define a system of explicit differential and (optionally) algebraic equations in state-space form. The state derivatives and outputs for a GENERAL_STATE_EQUATION may be user defined functions of the states, inputs, and time. The GENERAL_STATE_EQUATION is designed to model a nonlinear, time-varying system. It is especially useful in importing nonlinear system models developed elsewhere, into Adams. The set of coupled differential and algebraic equations which can be expressed in matrix notation as:
{(dX/dt)/Y} = {f({X},{U},t)}
The GENERAL_STATE_EQUATION definition is restricted to explicit functions of the states and inputs. However, because the VARIABLEs included in the u_input_array can be completely general, the user can write GENERAL_STATE_EQUATION equations that implicitly depend on any available Adams variable. The GENERAL_STATE_EQUATION follows standard control systems terminology, where X is the state array, Y is the output array, U is the input array, and IC is the initial condition array, X(t=0). In Adams View, each of these vectors is defined using an particular ARRAY. All ARRAY sizes must be consistent with the GENERAL_STATE_EQUATION definition. ARRAYs with zero-size and zero-valued partial derivative matrices should not be defined; Adams will correctly formulate the system equations based on those ARRAY statements and derivatives which do exist. The current values for the state derivative and output vectors of this GENERAL_STATE_EQUATION are computed in the user-supplied GSESUB subroutine (see the Adams Users Manual section on the "GSESUB"), much as the user would do for any other user-written subroutine. Additionally, the user must provide GSEXX, GSEXU, GSEYX and GSEYU subroutines (see the proper sections in the Adams Users Manual for a description of these routines) to compute the necessary internal partial derivatives in accordance with the values of df_dx_method, df_du_method, dg_dx_method, and the dg_du_method flags. Note that optional computation of these partial derivatives using finite differencing is planned for a future release of Adams.
Format:
part modify equation general_state_equation | |
|---|---|
general_state_equation_name = | an existing gse |
new_general_state_equation_name = | a new gse |
adams_id = | integer |
comments = | string |
state_equation_count = | integer |
discrete_state_equation_count = | integer |
output_equation_count= | integer |
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 |
df_dx_method = | gse_xxflag |
df_du_method = | gse_flag |
dg_dx_method = | gse_flag |
dg_du_method = | gse_flag |
static_hold = | on_off |
user_function = | real |
Example:
general_state_equation_name = | .model_1.gse_1 & |
|---|---|
adams_id = | 1 & |
x_state_array_name = | .model_1.array_18 & |
u_input_array_name = | .model_1.array_16 & |
y_output_array_name = | .model_1.array_17 & |
ic_array_name = | .model_1.array_19 & |
static_hold = | on & |
user_function = | 1.0 & |
state_equation_count = | 1 & |
output_equation_count = | 1 & |
interface_routines = | "force" & |
comments = | "none" |
Description:
Parameter | Value Type | Description |
|---|---|---|
general_state_equation_name | An Existing Gse | Specifies the general state equation to modify |
new_general_state_equation_name | A New Gse | Specifies the name of a new general 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 |
state_equation_count | Integer | Specifies the number of state equations to be used to define the system |
discrete_state_equation_count | Integer | Specifies the number of discrete state equations to be used to define the system |
output_equation_count | Integer | Specifies the number of output equations to be used to define the system |
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 |
discrete_state_array_name | An Existing Array | Specifies the array to represent the discrete state array |
discrete_ic_array_name | An Existing Array | Specifies the array name for stating the initial conditions of linear system |
df_dx_method | Gse_xxflag | Specifies how to compute the matrix of partial derivatives of the state equations with respect to the states |
df_du_method | Gse_flag | Specifies whether or not and how to compute the matrix of partial derivatives of the state equations with respect to the inputs |
dg_dx_method | Gse_flag | Specifies whether or not and how to compute the matrix of partial derivatives of the output equations with respect to the states |
dg_du_method | An Existing Matrix | Specifies whether or not and how to compute the matrix of partial derivatives of the output equations with respect to the inputs |
discrete | True_only | Specifies discrete GSE |
sample_period | Real | Specify sampling time |
static_hold | On_off | Indicates that the equations states are not changed during static and quasi-static analysis |
user_function | Real | Specifies the constants to be passed to GSESUB |
Extended Definition:
1. Specifies the general_state_equation to modify. You use this parameter to identify the existing general_state_equation to affect with this command. You may identify a general_state_equation by typing its name or by picking it from the screen. Since general_state_equation do not have a geometric position, Adams View displays general_state_equation icons at or near the model origin. If the general_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 general_state_equation icon is displayed. If you created the general_state_equation by reading an Adams data set or graphics file, the general_state_equation name is the letters GSE followed by the Adams data set general_state_equation ID number. The name of Adams GSE/101 is GSE101, for example. If you created the general_state_equation during preprocessing, you gave it a name at that time. If a general_state_equation is available by default, you may identify it by entering its name only. If it is not, you must enter its full name. To identify a general_state_equation under a different model, for instance, you may need to enter the model name as well. For example, you may specify general_state_equation 'fluid_volume' from model 'hydro' by entering ".hydro.fluid_volume'". If you type a "?", Adams View will list the general_state_equation available by default. You must separate multiple general_state_equation names by commas. If the general_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 general_state_equation picks by commas.
2. The new name specifies the name of the new general_state_equation. You may use this name later to refer to this general_state_equation. Adams View will not allow you to have two general_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 AdamsAdams 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 Adams Solver data file is written, the comments for an object are written before the statement corresponding to the object.
5. The ‘state equation count’ specifies the number of state equations (differential variables) that will be used in the definition of this system of equations (GENERAL_STATE_EQUATION). There must be at least one state in your GENERAL_STATE_EQUATION definition. The value range is 1 to 1200.
6. Discrete systems can be described by their difference equations. They are, therefore, represented in the state-space form as:
xd is called the state of the system, and contains n elements for an nth-order system. In matrix notation, xd is a column matrix of dimension nx1. u and y have the same meaning as for continuous systems.The fundamental difference between continuous and discrete systems is that the discrete or digital system operates on samples of the sensed plant data, rather than on the continuous signal. The dynamics of the controller are represented by recursive algebraic equations, known as difference equations, that have the form shown in Equations 8.The sampling of any signal occurs repetitively at instants in time that are T seconds apart. T is called the sampling period of the controller. In complex systems, the sampling period is not a constant, but is, instead, a function of time and the instantaneous state of the controller. The signal being sampled is usually maintained at the sampled value in between sampling instances. This is called zero-order-hold (ZOH). Determining an appropriate sampling period is a crucial design decision for discrete and sampled systems.One major problem to avoid with sampling is aliasing. This is a phenomenon where a signal at a frequency
produces a component at a different frequency 
simply because the sampling is occurring too infrequently. The general rule of thumb for such situations is as follows: If you want to avoid aliasing in a signal with a maximum frequency of 
, the sampling frequency is
calculated from 
. This is a lower limit for 
. If you want to obtain a reasonably smooth time response, then 
.The sampling rate for sampling the states of a discrete system must follow the above criterion to avoid aliasing
produces a component at a different frequency simply because the sampling is occurring too infrequently. The general rule of thumb for such situations is as follows: If you want to avoid aliasing in a signal with a maximum frequency of , the sampling frequency is calculated from . This is a lower limit for . If you want to obtain a reasonably smooth time response, then .The sampling rate for sampling the states of a discrete system must follow the above criterion to avoid aliasing 7. The ‘output equation count’ specifies the number of output equations (algebraic variables) that will be used in the definition of this system of equations (GENERAL_STATE_EQUATION). If OUTPUT_EQUATION_COUNT (the NO argument on the Adams GSE statement )is greater than 0, a Y_OUTPUT_ARRAY must also be specified. The value range is 0 to 1200.
8. The ‘X_state array name’ specifies the array in the model which will be used as the state array for this system element (GENERAL_STATE_EQUATION). An array with this name must be in the model and it may not be used in any other LINEAR_STATE_EQUATION, GENERAL_STATE_EQUATION, or TRANSFER_FUNCTION. If SIZE is specified for this ARRAY, it must equal the STATE_EQUATION_COUNT value.
9. The ‘U_input array’ specifies the array defined in the current model which will be used as the input (or control) array for this system element (GENERAL_STATE_EQUATION). The use of this parameter is optional. When the U_INPUT_ARRAY_NAME parameter is used, an U_INPUT_ARRAY with this name must be in the model, it must be of the U type and the user must also set either the DF_DU_METHOD or the DG_DU_METHOD, or both, to USER. The number of inputs to the GENERAL_STATE_EQUATION is inferred from the number of variable names given in the U_INPUT_ARRAY_NAME
10. The ‘Y output array name’ specifies the array name in the model which will be used as the output array for this system element (GENERAL_STATE_EQUATION). When the Y_OUTPUT_ARRAY_NAME parameter is used, an array with this name must be 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 set either the DG_DX_METHOD or the DG_DU_METHOD, or both, to USER. If SIZE is specified for this ARRAY, it must equal OUTPUT_EQUATION_COUNT value.
11. The ‘ic array name’ specifies the array name in the model which will be used as the initial conditions array for this system element (GENERAL_STATE_EQUATION). When the IC_ARRAY_NAME parameter is used, an array with this name must be in the model and it must have the same number of elements as the X_STATE_ARRAY (equal to the STATE_EQUATION_COUNT value). When no IC array is specified for a GENERAL_STATE_EQUATION, all states are initialized to zero.
12. If you selected Discrete or Sampled, for X array discrete, Enter the array element that is used to access the discrete states for the GSE. It must be of the X type, and it cannot be used in any other linear state equation, general state equation, or transfer function. for IC array discrete, Enter the array element that specifies the initial conditions for the discrete states in the system. The array is optional. The array element must be of the IC type. When you do not specify an IC array for a GSE, all the discrete states are initialized to zero.
13. If you select discrete, specify first sample time as the simulation time at which the sampling of the discrete states is to start. All discrete states before the first sample time are defined to be at the initial condition specified. The default is zero. Specify the sampling period associated with the discrete states of a GSE. This tells Adams Solver to control its step size so that the discrete states of the GSE are updated at:
last_sample_time + sample_period
In cases where an expression for the sampling period is difficult to write, you can specify it in a user-written subroutine GSE_SAMP. Adams Solver will call this function at each sample time to find out the next sample period.
14. The ‘df_dx method’ specifies how to compute the matrix of partial derivatives of the state equations with respect to the states. In the present release of Adams, the only possible value for this flag is USER, meaning that the user must provide a GSEXX subroutine to return the current values of these partial derivatives. See the Adams Reference Manual for additional information on how to incorporate these user provided routines. This parameter corresponds to the XXFLAG argument on the Adams GSE statement.
15. The ‘df_du method’ specifies whether or not and how to compute the matrix of partial derivatives of the state equations with respect to the inputs. In the present release of Adams, the only possible values for this flag are USER and NONE. USER means that the user must provide a GSEXU subroutine to return the current values of these partial derivatives, and NONE means that the state equations do not depend on the inputs. See the Adams Reference Manual for additional information on how to incorporate these user provided routines. This parameter corresponds to the XUFLAG argument on the Adams GSE statement.
16. The ‘dg_dx method’ specifies whether or not and how to compute the matrix of partial derivatives of the output equations with respect to the states. In the present release of Adams, the only possible values for this flag are USER and NONE. USER meaning that the user must provide a GSEYX subroutine to return the current values of these partial derivatives, and NONE means that the output equations do not depend on the states. See the Adams Reference Manual for additional information on how to incorporate these user provided routines. This parameter corresponds to the YXFLAG argument on the Adams GSE statement.
17. The ‘dg_du method’ specifies whether or not and how to compute the matrix of partial derivatives of the output equations with respect to the inputs. In the present release of Adams, the only possible values for this flag are USER, meaning that the user must provide a GSEYU subroutine to return the current values of these partial derivatives, and NONE, meaning that the output equations do not depend on the inputs. See the Adams Reference Manual for additional information on how to incorporate these user provided routines. This parameter corresponds to the YUFLAG argument on the Adams GSE statement.
18. 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.
19. The ‘user function’ specifies up to thirty constants which are passed to the user-written GSESUB subroutine that determines the current values of the state derivatives and outputs forming this GENERAL_STATE_EQUATION. These constants are also passed to the partial derivative subroutines, GSEXX, GSEXU, GSEYX, and GSEYU (also currently user_written). The FUNCTION argument must either be the last argument in the GSE statement list, or be followed by a backslash (\). See the Adams Reference Manual for additional information on the use of these routines.