part create equation differential_equation
Allows you to create or modify a user-defined differential equation.
A differential equation creates a user-defined state variable and defines a first-order differential equation that describes it. The equation can be dependent on any Adams Solver state variable available in a function expression except point-curve and 2D curve-curve constraints. You can create systems of differential equations using more than one differential equation, linear state equation, or general state equation.
Both, Adams FUNCTION expressions and user-written subroutines, can access the user-defined state variables and their derivatives.
FUNCTION expressions access the values by using the function DIF(i1) and the derivatives by using DIF1(i1). In each case, i1 specifies the ADAMS_ID of the differential equation that defines the variable.
User-written subroutines access the values and derivatives by calling the subroutine, DEQINF.
You describe the variable in a differential equation either by writing a function expression or user-written subroutine. Because it is easier to write function expressions than subroutines, you should use function expressions whenever possible to describe user-defined differential variables.
The equation defined by a FUNCTION expression or by a user-written subroutine may be in either explicit or implicit form. The following equation defines the explicit form of a differential equation:
y' = f (y, q, q', t)
In this equation, y' is the derivative of the user-defined state variable, y is the user-defined state variable itself, and q is a vector of Adams-defined state variables. If you cannot solve for the first derivative of the state variable, you need to use the implicit form. The following equation defines the implicit form of a differential equation:
0 = F (y, y', q, q', t)
Format:
part create equation differential_equation | |
|---|---|
differential_equation_name= | new equation |
adams_id= | integer |
comments= | string |
initial_condition= | real |
no_initial_condition= | true_only |
function= | function |
user_function= | real |
static_hold= | on/off |
implicit= | on/off |
routine = | string |
Description:
Parameter | Value Type | Description |
|---|---|---|
differential_equation_name | New Equation | Specifies the name of the equation to be created or modified |
adams_id | Integer | Assigns a unique ID number to the equation. |
Comments | String | Adds any comments about the equation to help you manage and identify it. |
initial_condition | Real | Specifies the initial value of the differential equation at the start of the simulation. |
no_initial_condition | True_only | Unsets the velocity initial condition for the specified equation (true) so it no longer has a velocity initial condition. |
Function | Function | Specifies a function expression or defines and passes constants to a user-written subroutine to define the differential equation. |
user_function | Real | Specifies up to 30 values for Adams Solver to pass to a user-written subroutine. |
Routine | String | Specifies an alternative library and name for the user subroutine DIFSUB. |
static_hold | On/off | Indicates that equation states are not permitted to change during static and quasi-static simulations (on). |
Implicit | On/off | Indicates that the function expression or subroutine defines the implicit form of the equation (on). |
Extended Definition:
1. When using the Adams View command language and naming entities, you can use the name later to refer to this entity. Adams View does not allow you to have two entities 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 of any length. For more information, see Using Extended Names. By enclosing the name in double quotes, you can 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 (for example, 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 Adams View assigns the default parent. If you type in the full name, then you can override the default parent. In most cases, when creating an entity, Adams View provides a default name. The default name that Adams View provides specifies the parentage that it has assumed. You can, of 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.
2. For comments, you can enter any alphanumeric characters. The comments that you create appear in the Information window when you select to display information about the object, in the Adams View log file, and in a command or dataset file when you export your model to these types of files. (Note that design variables are not output to datasets; therefore, neither are their comments.)
3. Initial_condition parameter may also specify in case of definition of an implicit equation, an approximate value of the initial time derivative of the differential equation at the start of the simulation. (You do not need to supply a second value when you enter an explicit equation because Adams Solver can compute the initial time derivative directly from the equation.)
Adams Solver might adjust the value of the time derivative when it performs an initial conditions simulation. Entering an initial value for the time derivative helps Adams Solver converge to a desired initial conditions solution.
4. Remember, leaving a velocity unset lets Adams View calculate the velocity of the part during an initial conditions simulation, depending on the other forces and constraints acting on the part. It is not the same as setting the initial velocity to zero.
5. Adams View treats the function parameter as a series of literal strings. When you write an Adams Solver dataset, Adams View writes these strings, just as you enter them here, after the 'FUNCTION=' argument.
If you want to define the equation with an expression, enclose the expression in quotes and enter it just as you would in the dataset.
If you want to define the equation with a user-written subroutine, enter the character string "USER(r1[,...,r30])", where r1[,...,r30] are the values you want Adams Solver to pass to your user-written subroutine DIFSUB. For example, if you enter "USER(1.,2.,3.)", Adams Solver calls your DIFSUB with values 1, 2, and 3. For more information, see the Adams Solver Subroutines online help
6. Many Adams Solver statements and commands feature the construct FUNCTION=USER(r1,r2,...,r30), which specifies that Adams Solver is to obtain element characteristics by loading and calling a specific user subroutine from a specific library of user subroutines. For example, Adams Solver calls the SFOSUB subroutine for the SFORCE statement.
The ROUTINE argument allows you to optionally specify an alternative library and user subroutine name for some or all elements.
The ROUTINE argument takes a string argument:
ROUTINE=libname::subname
The delimiter, ::, is required to separate the library name from the subroutine name. Both the libname and the subname are optional, but the :: delimiter is required to distinguish the library name. For example, to specify that a different subroutine name, mysfo, is to be loaded from the default subroutine library (the library that was mentioned when Adams Solver was run in run-user mode), you should write:
ROUTINE=mysfo
or
ROUTINE=::mysfo
If the default name (for example SFOSUB for SFORCE) is acceptable but the user subroutine is to be loaded from a library 'mylib', you must write:
ROUTINE=mylib::
The table below lists the default names for user subroutines for Adams Solver statements and commands.
Statement/Command | Default User Subroutine |
|---|---|
MOTION | MOTSUB |
FIELD | FIESUB |
SFORCE | SFOSUB |
STORQUE | SFOSUB |
MFORCE | MFOSUB |
GFORCE | GFOSUB |
VFORCE | VFOSUB |
VTORQUE | VTOSUB |
VARIABLE | VARSUB |
DIFF | DIFSUB |
SENSOR | SENSUB |
SENSOR | SEVSUB |
REQUEST | REQSUB |
CURVE | CURSUB |
SURFACE | SURSUB |
CONTROL | CONSUB |
COUPLER | See the COUPLER and GSE section below. |
GSE | See the COUPLER and GSE section below. |
Note: | The subroutine specified by the ROUTINE argument must have the same argument list as the default subroutine. Only the name is changed. Failure to satisfy this requirement results in unpredictable runtime failure. |
Just like many elements of a particular type can share the default user subroutine, many elements may share an alternative user subroutine. In other words, a group of your SFORCE elements may use the SFOSUB in the default library while a different group of SFORCE elements is using mylib::mysfo.
You can either fully qualify the name and location of the library or rely on Adams Solver to search for the library using predefined rules. For example, ROUTINE argument can specify absolute paths:
ROUTINE=/home/jdoe/mylibs/libsforces.so::sfo312
or relative paths with abbreviated library names:
ROUTINE=mylibs/sforces::sfo312
In the latter case, you would be relying on Adams Solver knowing to search in /home/jdoe (see the PREFERENCES statement (C++ or FORTRAN) for details about the library search path) and built-in search-rules that first look for the specified name, and failing that, try to prepend the lib prefix and an architecture specific suffix (.dll on the Microsoft Windows platform, .sl on the HP-UX platform and .so on other Linux platforms and Linux).
COUPLER and GSE
The COUPLER and GSE elements deserve special mention because they require more than one user subroutine.
The COUPLER element requires that three subroutines be provided. This is handled by providing a comma separated list of three libname::subname pairs, for example:
ROUTINE=lib1::cou1, lib2::cou2, lib3::cou3
where lib1, lib2, and lib3 can be three different libraries. The default names for these subroutines are COUSUB,COUXX,COUXX2, in that order.
The GSE case is further complicated by the fact that the GSE subroutine interface has recently been redesigned and the ROUTINE argument had been previously reserved to address the now deprecated GSESUB interface. To specify the new GSE_DERIV, GSE_OUTPUT, GSE_UPDATE, GSE_SAMP subroutines for GSE, use the INTERFACE argument:
INTERFACE=lib1::gse1,lib2::gse2,lib3::gse3,lib4::gse4
to specify the subroutines that default to GSE_DERIV, GSE_OUTPUT, GSE_UPDATE, GSE_SAMP, in that order. You can specify deprecated GSE subroutine interface using:
ROUTINE=lib1::gse1,lib2::gse2,lib3::gse3,lib4::gse4,lib5::gse5
to specify the subroutines that default to GSESUB, GSEXX, GSEXU, GSEYX, GSEYU, in that order.
7. 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.
