Output Elements

Output elements take care of inter-process communication. These elements can use specific communication means, depending on the type of simulation they are used for, and can communicate specific types of data.

Stream output

This is a special element which takes care of sending output to external processes by means of either local or inet sockets during batch or real-time simulations. This topic is under development, so expect frequent changes, and please do not count too much on backward compatibility.

The syntax is:

    <elem_type> ::= stream output

    <arglist> ::=
        stream name , " <stream_name> " ,
        create , { yes | no } ,
        [ { local , " <socket_name> " , |
            [ port , <port_number> , ]
            [ host , " <host_name> " , ] } ]
        [ { [ no ] signal
            | [ non ] blocking
            | [ no ] send first
            | [ do not ] abort if broken } [ , ... ] , ]
        [ output every, <steps> , ]
        [ echo , <file_name>
            [ , precision , <precision> ]
            [ , shift , <shift> ] , ]
        <content>

The stream output allows MBDyn to send streamed outputs to remote processes during both batch and real-time simulations, using sockets either in the local or in the inet namespace. If the simulation is run in real-time using RTAI, RTAI mailboxes are used instead.

• stream_name is the name of the RTAI mailbox where the output is written (a unique string no more than six characters long); it is basically ignored by the stream output element except when using RTAI;

• the create keyword determines whether the socket must be created or looked-up as already existing on the system;

• socket_name is the path of the local socket that is used to communicate between processes;

• port is the port number to be used with a inet socket. The default port number is 9011 (intentionally unassigned by IANA). If no host_name is given, localhost will be used;

• 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. The simulation will not start until the socket is created on the remote host;

• the flag no signal requests that no SIGPIPE be raised when sending through a socket when the other end is broken (by default, SIGPIPE is raised);

• the flag non blocking requests that operations on the socket do not block (or block, in case of blocking, the default);

• the flag no send first requests that no send occurs before the first time step (by default, data is always sent);

• the flag do not abort if broken requests that the simulation continues in case the connection breaks. No further data send will occur for the duration of the simulation (the default);

• the field output every requests output to occur only every steps;

• the field echo causes the content that is sent to the peer to be echoed on file file_name; the optional parameter precision determines the number of digits used in the output; the optional parameter shift is currently unused;

• the field content is detailed in the next section.

This element, when used with the motion content type, obsoletes the stream motion output element (see Section 8.19.3). When the simulation is executed in real-time using RTAI, this element obsoletes the RTAI output element (see Section 8.19.2).

Streamed output

Different types of data can be sent. The most general form is called values, consisting in an arbitrary set of independent scalar channels. A form specifically intended to communicate the motion of a mechanical system is called motion, consisting in a subset of the kinematics of a set of structural nodes:

    <content> ::= { <values> | <motion> }

    <values> ::= [ values , ]
        <channel_number> ,
            <value>
            [ , ... ]

    <value> ::= {
        [ nodedof , ] (node_dof) <output_dof>
        | drive , (DriveCaller) <drive_data>
    }

    <motion> ::= motion ,
        [ output flags ,
            { position
            | orientation matrix
            | orientation matrix transpose
            | velocity
            | angular velocity } [ , ... ] , ]
        { all | <struct_node_label> [ , ... ] }

where

• the (optional) keyword values indicates that a set of independent scalar channels is output by the element;

• the number of channels channel_number that are written determines how many value entries must be read. In case of node_dof (the default, deprecated), they must be valid scalar dof entries, which can be connected in many ways to nodal degrees of freedom; in case of drive_data, they can be arbitrary functions, including node or element private data;

• the keyword motion indicates that a subset of the kinematic parameters of a set of structural nodes is output by the element. As opposed to the values case, which is intended for generic interprocess communication output, this content type is intended to ease and optimize the output of the motion of structural nodes, to be used for on-line visualization purposes. By default, only the position of the selected nodes is sent. This is intended for interoperability with a development version of EasyAnim which can read the motion info (the so-called ``van'' file) from a stream. The optional keyword output flags allows to request the output of specific node kinematics: the node position, orientation matrix (either row- or column-major), the velocity and the angular velocity. The default is equivalent to output flags, position.

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 would be known as by RTAI; it must be no more than 6 characters long, and mostly useless;

• the instruction create determines whether MBDyn will create the socket, or try to connect to an existing one;

• 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 9011 (intentionally unassigned by IANA);

• the flag no signal is honored;

• the flag non blocking is honored;

• the flag no send first is honored;

• the flag do not abort if broken is honored.

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 be exactly 6 characters long;

• 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 flag no signal is ignored;

• the flag non blocking is honored; however, blocking mailboxes make little sense, and real-time synchronization using RTAI should not rely on blocking mailboxes;

• the flag no send first is ignored (although it should be honored when the mailbox is blocking);

• the flag do not abort if broken is ignored; the program is always terminated if a mailbox is no longer available.

RTAI output

This element is actually used only when the simulation is scheduled using RTAI; otherwise, the corresponding stream output element is used (see Section 8.19.1). As a consequence, its explicit use is discouraged and deprecated. The stream output element should be used instead.

Stream motion output

This element type is obsoleted by the stream output element with the motion content type (see Section 8.19.3). The syntax is:

    <elem_type> ::= stream motion output

    <arglist> ::= 
        stream name , " <stream_name> " ,
        create , { yes | no } ,
        [ { local , " <socket_name> " , |
            [ port , <port_number> , ]
            [ host , " <host_name> " , ] } ]
        [ { [ no ] signal
            | [ non ] blocking
            | [ no ] send first
            | [ do not ] abort if broken } [ , ... ] , ]
        <motion>

Its support may be discontinued in the future.

Structural output

TODO.