File Drivers

The file drivers are defined by the statement

    file : <arglist> ;

A comprehensive family of file drivers is planned; their syntax is:

    <arglist> ::= <label> , <normal_arglist>

The following file drivers are supported at present:

Fixed Step

    <normal_arglist> ::= fixed step , 
        { count | <steps_number> } ,
        <columns_number> ,
        <initial_time> ,
        <time_step> 
        [ , interpolation , { linear | const } ]
        { , [ pad zeroes , { yes | no } , ]
         | [ bailout, { none | upper | lower | any } , ] }
        " <file_name> "

The value at an arbitrary time is interpolated from the available data.

If the requested value is out of time bounds, zero is returned, unless pad zeroes is set to no, which means that the first or the last set of values is respectively used. As an alternative, if bailout is set to upper, lower or any, the simulation is stopped as soon as the time goes out of the respective ''time`` bounds.

If interpolation is linear (the default), a linear interpolation is used. Otherwise, if interpolation is const, the value at the beginning of the time step that includes the current time is used.

The file format is

# an arbitrary number of lines starting with `#'
#
# channel #1 channel #2 ... channel #n
  1.         2.         ... 100.
...

Variable Step

    <normal_arglist> ::= variable step , 
        <columns_number> ,
        [ , interpolation , { linear | const } ]
        { , [ pad zeroes , { yes | no } , ]
         | [ bailout, { none | upper | lower | any } , ] }
        " <file_name> "

The file format is

# an arbitrary number of lines starting with `#'
#
# time channel #1 channel #2 ... channel #n
  0.   1.         2.         ... 100.
...

Time values must grow monotonically.

Socket

    <normal_arglist> ::= socket , 
                         <columns_number>
                         { , local, " <file_name> " 
                           | [ , port, <port_number> ] }
                         (AuthenticationMethod)<authentication>

The driver binds to a socket listening on port port_number (defaults to 5555) or on the named pipe file_name; at the beginning of each time step, in case of connection, the driver expects some input data in text format, consisting in an authentication token (if required). The authentication token is usually in the form

    user: <user_name> <new_line>
    password: <user_password> <new_line>

Note: white-spaces may be significant in user_name, and surely are in user_password.
It is followed by a label token, in the form

    label: <label> <new_line>

indicating the column being edited, followed by the desired changes; the connection is terminated by a single mark followed by a newline:

    . <new_line>

The permitted operations, at present, are:

    value: <value> <new_line>

sets the value the drive will assume from the current step on

    inc: { yes | no } <new_line>

tells whether to switch on or off the increment mode, resulting in subsequent value commands being ``set'' rather than ``add''

    imp: { yes | no } <new_line>

tells whether to switch on or off the impulse mode, resulting in subsequent value commands to be applied for one step only.
Note: at present, impulse mode supersedes any incremental mode, namely the value of the drive is reset to zero after one step. This behavior may change in the future.

RTAI Mailbox

This special drive is a variant of the Socket Stream (Section 7.1.5; under development yet) that reads the input data from a RTAI mailbox in non-blocking mode. It is intended as a means of communication between different processes running in real-time. The syntax is:

    <normal_arglist> ::= RTAI input ,
        stream drive name , " <stream_name> " ,
        [ create , { yes | no } , ]
        [ host , " <host_name> " , ]
        [ { [ non ] blocking } , [ ... ] ]
        <columns_number> ;

where

• stream_name is the name of the mailbox (a unique string no more than 6 characters long);
• the create keyword determines whether the mailbox must be created or looked-up as already existing on the system;
• host_name is the name or the IP of the remote host where the mailbox resides; note that if this field is given, create must be set to no and the mailbox must be already defined on the remote host;
• the number of channels columns_number determines how many columns can be accessed via the file drive caller mechanism of Section 2.5.21, as for all the other file drivers.

This part of the program is rapidly evolving, so do please not expect too much documentation and backwards compatibility.

Note: at present, these elements require that the simulation be run in real-time mode (see Section 4.1.5); future development will allow to emulate the use of these elements also when the simulation is not run in real-time, e.g. for modeling or model debugging purposes.

Stream

    <normal_arglist> ::= stream,
        name , " <stream_name> " ,
        create , { yes | no } ,
        [ { local , " <socket_name> " , |
            [ port , <port_number> , ]
            [ host , " <host_name> " , ] } ]
        [ { [ no ] signal
            | [ non ] blocking } , [ ... ] ]
        [ input every , <steps> , ]
        [ timeout , <timeout> , ]
        [ echo , " <echo_file_name> "
            [ , precision , <precision> ]
            [ , shift , <shift> ] , ]
        <columns_number>

The stream drive allows MBDyn to receive streamed inputs from remote processes both during regular simulations and during real-time simulations under RTAI. If the simulation is run in real-time, it uses RTAI mailboxes, otherwise regular UNIX sockets are used, either in the local or in the internet namespace.

This drive type is intended to allow the development of real-time models by running regular simulations for the purpose of debugging the model and the control process without the overhead and the potential problems of running in real-time. Then the same model can be run in real-time without changing the details of the communication with the controller process.

Non real-time simulation

During non real-time simulations, streams operate in blocking mode. The meaning of the parameters is:

• stream_name indicates the name the stream will be known as; it is mostly useless, and must be no more than 6 characters long, since it is only allowed for compatibility with RTAI's mailboxes;
• the instruction create determines whether the socket will be created or looked for by MBDyn;
• the keyword local indicates that a socket in the local namespace will be used; if create is set to yes, the socket is created, otherwise it must exist.
• either of the keywords port or host indicate that a socket in the internet namespace will be used; if create is set to yes, host_name indicates the host that is allowed to connect to the socket; it defaults to any host (0.0.0.0); if create is set to no, host_name indicates what host to connect to; the default is localhost (127.0.0.1); the default port is 5500;
• the keyword no signal disables raising a SIGPIPE in case the stream is read after it was closed by the peer;
• the keyword input every allows to read new driver values every steps time steps;
• the keyword timeout allows to set a timeout for each read operation; the timeout is expressed in seconds as a floating point number, with a theoretical micro-second resolution (the actual resolution is left to the OS);
• the keyword echo allows to echo the streamed data into file echo_file_name, using the optional precision and a shift for the time, to make sure step changes are captured correctly (a small negative value is recommended); the resulting file is suitable to re-execute the simulation using a variable step file driver, using a const value for the interpolation option.

If no socket type is specified, i.e. none of the local, port and host keywords are given, a socket is opened by default in the internet namespace with the default IP and port; the create keyword is mandatory.

Real-time simulation

During real-time simulations, streams wrap non-blocking RTAI mailboxes. The meaning of the parameters is:

• the parameter stream_name indicates the name the stream will be known as in RTAI's resource namespace; it must no more than 6 characters long, and actually represents the mailbox name;
• the instruction create determines whether the mailbox will be created or looked for by MBDyn;
• the keyword local is ignored;
• the keyword host indicates that a mailbox on a remote host will be used; it is useless when create is set to yes, because RTAI does not provide the possibility to create remote resources; if none is given, a local mailbox is assumed;
• the keyword port is ignored.

The parameter columns_number determines how many channels will be used. A channel is a double typed number; a stream drive can read an arbitrary number of simultaneous channels.