Adams Advanced Package > Adams Co-Simulation Interface > Adams Co-Simulation Interface (ACSI) > Configuration script

Configuration script

 
Definitions
Legend
The configuration script uses a simple syntax. A configuration script is a list of keyword=value entries and named groups of keyword=value entries. All keywords and group names are case sensitive. Comment lines start with either a $, #, or a ! sign.
For example, for the co-simulation illustrated in Figure 14, the configuration script looks like this:
#-------------------------------------------
# Spring damper test example
#-------------------------------------------
 
cosim_ip = 127.0.0.1
 
# Adams process
process {
id = 99
name = Rigid parts and springs
code = adams
 
interaction {
gforce_id = 1
name = gforce1
connection = rigid1
}
 
interaction {
gforce_id = 2
name = gforce2
connection = rigid2
}
}
 
# Marc process
process {
id = 3
name = Intermediate block
code = marc
 
interaction {
node_id = 2
name = rigid1
connection = gforce1
}
 
interaction {
node_id = 3
name = rigid2
connection = gforce2
}
}
 
An example of a configuration script where Adams co-simulates with Marc and EDEM follows:
 
#-------------------------------------------
# Example of Adams, Marc and EDEM
#-------------------------------------------
 
cosim_ip = 127.0.0.1
 
# Adams process
process {
id = 99
name = Rigid parts and springs
code = adams
 
interaction {
name = gforce1
connection = Box
gforce_id = 1
}
 
interaction {
name = GFORCE_2
connection = Left_node
gforce_id = 2
}
 
interaction {
name = GFROCE_3
connection = Right_node
gforce_id = 3
}
}
 
# Marc process
process {
id = 3
name = Intermediate block
code = marc
 
interaction {
name = Left_node
connection = GFORCE_2
node_id = 1332
}
 
interaction {
name = Right_node
connection = GFROCE_3
node_id = 1333
}
}
 
# EDEM process
process {
code = edem
name = Box
id = 50
ip_address = 127.0.0.1
 
interaction {
name = Box
connection = gforce1
geometry_name = Box
}
}
 
All keywords are case sensitive. Shown below is the complete list of keywords supported for this release.

Definitions

The following terms are used in all descriptions below. 'Co-simulation global reference frame 'stands for the ensemble global reference frame for all models (Adams, Marc and EDEM) being co-simulated. It is the user's decision to select the co-simulation global reference frame. As mentioned above, each model has its own global reference frame. The models' global reference frames need not coincide with the co-simulation global reference frame.
'Co-simulation units' stands for the ensemble units used by the executable Glue code. Each co-simulating model can have different units. Options allow the user to set conversion factors eliminating the need to modify existing data sets.
 

Legend

 
Syntax
 
Example
Explanation

Configuration directives

 
check = [yes | no]
 
check = yes
Global. Optional.

If set to "yes", the Glue code will stop after processing and verifying the configuration script.

Default is no.
 
code = [ adams | marc | edem ]
 
code = adams
Used inside a process group. Required.

Defines the type of code for a process. Notice we support only Adams, Marc and EDEM but we will support other codes in the future.
 
connection = [string]
 
connection = rigid1
Used in an interaction group.

Required.

Sets the name of some other interaction that is connected to the interaction being defined.
 
cosim_ip = [string]
 
cosim_ip = 182.23.22.222
Global, optional.

Sets the IP number of the host running the main Glue code (the main executable). Set this number to 127.0.0.1 if all codes are running on the same host. This option is required if a secondary job is running from a different host than the one running the Glue code.

Default is 127.0.0.1
 
cosim_port = [integer]
 
cosim_port = 4456
Global, optional.

Sets the number of the TCP/IP port number used by the Glue code. The default value ought to be fine for most servers. In case there is a conflict, use this option to set the port number. If a server is running multiple co-simulation jobs, each job must have a different port number.

Users must set this value if multiple co-simulations are being run by the same host.

Default is 12341.
 
damping = [real]
 
damping = 0.002
Used inside a Marc process group.

Optional.

Defines the damping added by Adams in addition to the stiffness matrix. Adams creates a damping matrix equal to the value supplied by the user times the value of the stiffness matrix. The value has no units.

Default is zero.
 
debug = [string…]
 
debug = basic, forces, displacements
Global, optional. Set this option to a list of keywords.
Enforces the ACSI to print debugging information in the log files. Supported keywords are:
1. basic. Enables printing basic information like simulation time, titles, analysis mode and so on.
2. gforce. Enables printing information of GFORCE computations in the Adams model.
3. forces. Enables printing force information in both Adams and Marc.
4. displacements. Enables printing displacement information computed by Adams.
5. io. Enables printing I/O information happening between co-simulating codes.
6. detail. Enables additional more details on kinematic computed by Adams, more info on which code is stepping and so on.
7. matrices. Enables printing the tangent stiffness matrix computed by MSC Marc.
8. all. Enables printing all available debugging information.
Default is empty (no debugging)
 
 
execution_command = [string]
 
execution_command = C:\Program Files\MSC.Software\Adams\20XX\solver\acsi\model.acf
Used inside any process group.

Optional.

Specifies the complete path, executable name, optional flags and model name used to launch a process. This option may be used to launch any co-simulating process. If this option is not specified or if the value is empty, then the ACSI will ignore it and the user will be prompted to launch the process manually.

This option must be used to launch a process on the same machine the ACSI glue code (or GUI) is running. You may not launch a process across the network.

This option allows users to use environment variables. See more details in section Automatic local launch. See also the Option working_directory.

Default: Empty string.
 
force_absolute_error= [real]
 
force_absolute_error = 0.001
Global. Optional.

Defines the absolute error used by the error control of forces. See section Theoretical background for more details.

Default is 0.01.
 
 
force_relative_error= [real]
 
force_relative_error = 0.001
Global. Optional.

Defines the relative error used by the error control of forces. See section Theoretical background for more details.

Default is 0.01.
 
geometry_name = [string]
 
geometry_name = truck_wheel
Used inside an EDEM interaction group.

Required.

Defines the case-sensitive name of the EDEM geometry used as an interaction. This geometry must exist in the simulation deck.
 
gforce_id = [integer]
 
gforce_id = 88
Used inside an Adams interaction group. Required.

Defines the Adams ID of a GFORCE used as an interaction. This GFORCE must use the USER() option and the ROUTINE option must be set to the name of the provided shared library ACSI_Adams. For example:
GFORCE/1
, I = 16
, JFLOAT = 18
, RM = 17
, FUNCTION = USER(0)\
, ROUTINE = ACSI_Adams
 
Library ACSI_Adams.dll (or ACSI_Adams.so) is included in the distribution.
 
 
 
id = [integer]
 
id = 8
Used in process group, required.

Sets the process number. Every process must have a unique arbitrary and distinct integer number. This id is used by all codes to ensure proper communication.
 
info = [string]
 
info = Rubber block
Global, optional.

Sets an info sentence to describe the co-simulation model.

Default is empty.
 
info_step = [real]
 
info_step = 0.25
Global. Optional.

Defines the time interval to send info messages by the co-simulation. This quantity is not related to the communication interval between the co-simulating codes. It simply defines how often informational messages are sent to the user.

Default is 0.10 (co-simulation units)
 
interaction {
…
}
 
interaction {
Used inside a process group.

Defines an interaction group of data. The keyword interaction and the opening curly bracket "{" must be written on the same line. The group of data must end with a closing curly bracket "}" on a single line. See example above.
 
interpolation_order_f = [-2 | -1 | 0 | 1 | 2]
 
interpolation_order_f = 0
Global. Optional.

Defines the interpolation algorithm to be used to extrapolate forces passed to the Adams process. See section Theoretical background for more details.

Default is 2.
 
interpolation_order_u = [-2 | -1 | 0 | 1 | 2]
 
interpolation_order_u = -1
Global. Optional.

Defines the interpolation algorithm to be used to interpolate displacements passed to Marc/EDEM processes. See section Theoretical background for more details.

Default is 2.
 
ip_address = [string]
 
ip_address = 128.64.64.20
Used inside an EDEM process group.

Optional.

Defines the IP address of the host running the EDEM process.

Defaults to the localhost 127.0.0.1.
 
linear_weight_f = [real]
 
linear_weight_f = 0.6
Global. Optional.

Defines the weight to be used in computing a slope for a linear extrapolation of forces passed to the Adams process. See section Theoretical background for more details.

Default is 0.9.
 
 
linear_weight_u = [real]
 
linear_weight_u = 0.6
Global. Optional.

Defines the weight to be used in computing a slope for a linear interpolation of displacements passed to Marc/EDEM processes. See section Theoretical background for more details.

Default is 0.9.
 
model_orientation = [real, real, real,…]
 
model_orientation = 0,0,1,1,0,0,0,1,0
Used in process group. Optional.

Sets the orientation of the global reference frames a model relative to the co-simulation global reference frame. The data are 9 values for the orthogonal rotation matrix [A] that pre-multiplies a vector in the model reference frame to obtain a vector in the co-simulation reference frame. Values are entered in row order, namely a11, a12, a13, a21, a22,…, a33.

Default is 1,0,0,0,1,0,0,0,1. (Model's global reference frame is oriented coincident with Co-simulation reference frame.)
 
 
model_origin = [real, real, real]
 
model_origin = 1,2,4
Used in process group. Optional.

Sets the location of the global reference frame of a co-simulating model, relative to the co-simulation global reference frame.

This option allows users have different reference frames for all models.

The location must be given in co-simulation reference frame and using co-simulation units.

Default is 0,0,0. (Model's global reference frame is coincident with Co-simulation reference frame.)
 
node_id = [integer]
 
node_id = 3
Used inside a Marc interaction group.

Required.

Defines the Marc ID of a node used in an interaction. The node must have a FIXED DISP boundary condition of type 3, indicating that its degrees of freedom are prescribed by Adams. See also Marc Volume C: Program input. In Mentat, the corresponding Boundary Condition Method is called Co-Sim Int. Node.
 
 
process {
…
}
 
process {
Defines a process group of data. The keyword process and the opening curly bracket "{" must be written on the same line. The group of data must end with a closing curly bracket "}" on a single line. See example above.
 
name = [string]
 
name = Rubber soft block
Used in process or interaction groups. Required.

When inside a process group, sets an arbitrary name for a process. This name is used by the Glue code to prompt the user to start a particular process or to print error messages.

When inside an interaction group, sets the name of the interaction. This name is used by other interaction group to set the topology of the co-simulation.
 
single_threaded = [yes | no]
 
single_threaded = yes
Global, optional.

Forces the co-simulation to use either a multithreaded solution or single threaded solution.

Default is 'no' (all secondary processes run in parallel by default).
 
statics_step_size = [real]
 
statics_step_size = 1.e-7
Used inside a Marc process group.

Optional.

Defines the size of the time step taken by Marc per each Adams iteration during static simulations. Units are time units in the Marc model.

Default is 1.e-6.
 
timeout = [integer]
 
timeout = 30
Global. Optional.

Specifies a period (in seconds) after which the ACSI executable will abort launching a process if no handshaking with the process has been detected. This option is always used with option execution_command.

When launching a process, the ACSI will wait up to the specified timeout for that process to start. If no handshaking is detected before the timeout goes off, the ACSI will abort the co-simulation.

Default: 10.
 
transfer_fraction = [real]
 
transfer_fraction = 0.1
Used inside an EDEM process group.

Optional.

This parameter is used to compute how often the EDEM process communicates with the Glue code to transfer force data and request motion data, at each interaction point. See section Using the transfer_fraction option for a detailed explanation on how we use this parameter.

A value of 1 means that the transfer of force/displacement data only happens at every Adams time step, so EDEM will simulate fully up until the Adams simulation time.

A value of 0 means that the data transfer happens at every EDEM time step.

Default is 0.5
 
units_force = [real]
 
units_force = 2.2
Used in process group. Optional.

Sets the conversion factor that multiplies a force value in model units to obtain a force value in co-simulation units.

Default is 1. (Model has same force units as co-simulation force units)
 
units_length = [real]
 
units_length = 0.001
Used in process group. Optional.

Sets the conversion factor that multiplies a length value in model units to obtain a length value in co-simulation units.

Default is 1. (Model has same length units as co-simulation length units)
 
units_time = [real]
 
units_time = 1000
Used in process group. Optional.

Sets the conversion factor that multiplies a time value in model units to obtain a time value in co-simulation units.

Default is 1. (Model has same time units as co-simulation time units)
 
working_directory = [string]
 
working_directory = D:\My Models\test001
Used inside any process group.

Optional.

Specifies the complete path to the working directory for the corresponding process. This option is ignored if the execution_command option is missing or empty.

This option allows users to use environment variables. See more details in section Automatic local launch. See also the Option working_directory.

Default: Empty string.