• 1 Introduction
• 2 Legend
• 3 Element Name
• 4 Types
  • 4.1 Scalar Type
  • 4.2 Vector Type
  • 4.3 Matrix Type
• 5 Parameters
• 6 Expression Evaluator
  • 6.1 Octave Expression Evaluator
  • 6.2 Python Expression Evaluator
• 7 Symbolic Functions
  • 7.1 Octave Symbolic Functions
  • 7.2 Python Symbolic Functions
• 8 Embeding
• 9 Measurements
  • acceleration
  • amount
  • angle
  • area
  • bulkModulus
  • current
  • damping
  • density
  • dynamicViscosity
  • flow
  • force
  • illumination
  • inertia
  • kinematicViscosity
  • length
  • mass
  • nounit
  • pressure
  • stiffness
  • temperature
  • time
  • torque
  • velocity
  • volume

1 Introduction

2 Legend

3 Element Name

Elements which must be referable must have a name. Mostly this name is given by the attribute name. A valid name starts with a letter or a underscore. The following characters can be letters, underscores or digits. The content between '{' and '}' can be any Expression Evaluator and is substituted by the result of the evaluator (which must be a valid name; normal a integer number).

The following table shows examples for valid element names (on the left) and the substituted names (on the right), if there exist a scalar (integer) parameter of name n with the value 2:

4 Types

4.1 Scalar Type

A scalar type can be of any unit defined in measurements. The unit is given by a optional attribute of name unit. The type name of a scalar of measure length is pv:lengthScalar and so on. Where pv is mapped to the namespace-uri http://www.mbsim-env.de/MBXMLUtils.

The content of a scalar type must be a Expression Evaluator. The following examples are valid, if there exist a scalar paremter a and b in the parameter file:

<myScalarElement unit="mm">4*sin(a)+b</myScalarElement>

<myScalarElement>[a,2]*[3;b]</myScalarElement>

There is also a special unit of name unknown defined. This unit dose not take the optional unit attribute, it takes an optional attribute of name convertUnit. The value of this attribute can be a Expression Evaluator which must contain a parameter of name value. The given value is then converted by this expression.

4.2 Vector Type

A vector type can be of any unit defined in measurements. The unit is given by a optional attribute of name unit. The type name of a vector of measure length is pv:lengthVector and so on. Where pv is mapped to the namespace-uri http://www.mbsim-env.de/MBXMLUtils.

The content of a vector type can be one of the following:

• A Expression Evaluator. The following examples are valid, if there exist a scalar paremter a and b in the parameter file:

  <myVectorElement unit="mm">[1;b;a;7]</myVectorElement>

  <myVectorElement>[a,2;5.6,7]*[3;b]</myVectorElement>

  Using the corresponding evaluator command it is also possible to load the data from a external file (for octave):

  <myMatrixElement>ret=load('mydata.dat')</myMatrixElement>

• A XML representation of a vector: The following shows a example of such a XML representation.

  <myVectorElement>
    <pv:ele>6.5</pv:ele>
    <pv:ele>1.5</pv:ele>
    <pv:ele>7.3</pv:ele>
  </myVectorElement>
  

For the special unit of name unknown see Scalar Type

4.3 Matrix Type

A matrix type can be of any unit defined in measurements. The unit is given by a optional attribute of name unit. The type name of a matrix of measure length is pv:lengthMatrix and so on. Where pv is mapped to the namespace-uri http://www.mbsim-env.de/MBXMLUtils.

The content of a matrix type can be one of the following:

• A Expression Evaluator. The following examples are valid, if there exist a scalar paremter a and b in the parameter file:

  <myMatrixElement unit="mm">[1,b;a,7]</myMatrixElement>

  <myMatrixElement>[a,2;5.6,7]*rand(2,2)</myMatrixElement>

  Using the corresponding evaluator command it is also possible to load the data from a external file (for octave):

  <myMatrixElement>ret=load('mydata.dat')</myMatrixElement>

• A XML representation of a matrix: The following shows a example of such a XML representation.

  <myMatrixElement>
    <pv:row>
      <pv:ele>6.5</pv:ele>
      <pv:ele>1.5</pv:ele>
    </pv:row>
    <pv:row>
      <pv:ele>6.5</pv:ele>
      <pv:ele>1.5</pv:ele>
    </pv:row>
  </myMatrixElement>
  

For the special unit of name unknown see Scalar Type

5 Parameters

A example for a parameter file is given below:

<Parameter xmlns="http://www.mbsim-env.de/MBXMLUtils">
  <scalarParameter name="N">9</scalarParameter>
  <vectorParameter name="a">[1;2;3]*N</vectorParameter>
  <scalarParameter name="lO">0.2*N</scalarParameter>
  <matrixParameter name="A">[1,2;3,4]</matrixParameter>
  <anyAarameter name="p">{'test', 4, 6.0}</anyParameter>
  <import>'/home/user/octaveScripts'</import>
  <import action="someString">'/home/user/octaveScripts'</import>
</Parameter>

The parameter names must be unique. The parameters are added from top to bottom. Parameters may depend on parameters already added. The parameter values can be given as Expression Evaluator. Hence a parameter below another parameter may reference this value.

<scalarParameter>, <vectorParameter> and <matrixParameter> define a parameter value of type scalar, vector and matrix, respectively. <anyParameter> defines a parameter value of any type the evaluator can handle, e.g. a cell array or struct for octave. <import> is highly dependent on the evaluator and does not have a 'name' attribute but an optional 'action' attribute which defaults to '': it imports submodules, adds to the search path or something else. See at a specific evaluator for details about what it does for this evaluator.

6 Expression Evaluator

Different expression evaluators can be used. Currently implemented is python and octave as evaluator. This description of this general section is based on the octave expression evaluator, but all other evaluators are similar. See the sub-sections for details.

A octave expression/program can be arbitary octave code. It can be a single statement or a statement list.

If it is a single statement, then the value for the XML element is just the value of the evaluated octave statement. The type of this value must match the type of the XML element (scalar, vector or matrix; any can hold any value). The following examples shows valid examples for a single octave statement, if a scalar parameter of name a and b exist:

4

b

3+a*8

[4;a]*[6,b]

If the text is a statement list, then the value for the XML element is the value of the variable 'ret' which must be set by the statement list. The type of the variable 'ret' must match the type of the XML element (scalar, vector or matrix). The following examples shows valid examples for a octave statement, if a scalar parameter of name a and b exist:

if 1==a
  ret=4
else
  ret=8
end

results in 4 if a==1 else results in 8.

myvar=[1;a]
myvar2=
ret=myvar2*b
dummy=3

results in a vector of two elements where the first is 2*b and the second is 2*a*b.

Note that the characters '&', '<' and '>' are not allowed in XML. So you have to quote them with '&amp;', '&lt;' and '&gt;', or you must enclose the octave code in a CDATA section:

<![CDATA[
function r=myfunc(a)
  r=2*a;
end
if 1 & 2, x=9; else x=8; end
ret=myfunc(m1/2);
]]>

The following m-functions extent the octave functionality being useful for several applications:

\(\text{rotateAboutX}(\varphi)\)

Returns the transformation matrix by angle \(\varphi\); around the x-axis: \[ \left[\begin{array}{ccc} 1 & 0 & 0 \\ 0 & \cos(\varphi) & -\sin(\varphi) \\ 0 & \sin(\varphi) & \cos(\varphi) \end{array}\right] \]

\(\text{rotateAboutY}(\varphi)\)

Returns the transformation matrix by angle \(\varphi\); around the y-axis: \[ \left[\begin{array}{ccc} \cos(\varphi) & 0 & \sin(\varphi) \\ 0 & 1 & 0 \\ -\sin(\varphi) & 0 & \cos(\varphi) \end{array}\right] \]

\(\text{rotateAboutZ}(\varphi)\)

Returns the transformation matrix by angle \(\varphi\); around the z-axis: \[ \left[\begin{array}{ccc} \cos(\varphi) & -\sin(\varphi) & 0 \\ \sin(\varphi) & \cos(\varphi) & 0 \\ 0 & 0 & 1 \end{array}\right] \]

\(\text{cardan}(\alpha,\beta,\gamma)\)

Returns the cardan transformation matrix: \[ \left[\begin{array}{ccc} \cos(\beta)\cos(\gamma) & -\cos(\beta)\sin(\gamma) & \sin(\beta) \\ \cos(\alpha)\sin(\gamma)+\sin(\alpha)\sin(\beta)\cos(\gamma) & \cos(\alpha)\cos(\gamma)-\sin(\alpha)\sin(\beta)\sin(\gamma) & -\sin(\alpha)\cos(\beta) \\ \sin(\alpha)\sin(\gamma)-\cos(\alpha)\sin(\beta)\cos(\gamma) & \cos(\alpha)\sin(\beta)\sin(\gamma)+\sin(\alpha)\cos(\gamma) & \cos(\alpha)\cos(\beta) \end{array}\right] \]

\(\text{euler}(\Phi,\theta,\varphi)\)

Returns the Euler transformation matrix: \[ \left[\begin{array}{ccc} \cos(\varphi)\cos(\Phi)-\sin(\varphi)\cos(\theta)\sin(\Phi) & -\cos(\varphi)\cos(\theta)\sin(\Phi)-\sin(\varphi)\cos(\Phi) & \sin(\theta)\sin(\Phi) \\ \cos(\varphi)\sin(\Phi)+\sin(\varphi)\cos(\theta)\cos(\Phi) & \cos(\varphi)\cos(\theta)\cos(\Phi)-\sin(\varphi)\sin(\Phi) & -\sin(\theta)\cos(\Phi) \\ \sin(\varphi)\sin(\theta) & \cos(\varphi)\sin(\theta) & \cos(\theta) \end{array}\right] \]

\(\text{installPrefix}()\)

Returns the absolute path of the MBSim-Env installation.

\(\text{invCardan}(T)\)

Returns the inverse of cardan, see above.

\(\text{rgbColor}(r,g,b)\)

Returns the HSV color used by OpenMBV from the given red, green and blue values.

\(\text{tilde}(x)\)

If x is a 3 vector returns the screw symmetric 3x3 matrix for cross product calcuation. If x is a 3x3 matrix the inverse function is used.

\(\text{registerPath}(filename)\)

Adds filename to the list of file on which the model depends (e.g. used for FMU export).

\(\text{getOriginalFilename}()\)

Returns the filename where this statement was defined before the Embeding was done.

\(\text{load}(filename)\)

Loads filename as a CSV file and return the date as a matrix. Details depend on the evaluator, octave or python.

6.1 Octave Expression Evaluator

Each evaluation is done in a clean octave context with:

octave globals:

being preserved between each call but only inside of one instance of the evaluator.

octave locals:

set to the "current parameters"

Where "current parameters" are all parameters of the current parameter stack. The result is the value of the variable "ret", if given. Else its the value of the variable "ans", if given (note that octave stores the result of expressions in a variable named "ans"). Else, if the code was just the name of another variable the result is the value of this variable.

addImport/<import> does a usual evaluation and the resulting string is added to the octave path [is does more but the exact behaviour is currently not very well defined, try to avoid 'import' in octave].

6.2 Python Expression Evaluator

Each evaluation is done in a clean python context with:

globals():

set to the following key-value pairs, in order, where keys are overwritten if already existing:

• python __builtins__
• the key-values of the global import list (this list is deprecated and should be empty)
• the key-values of the current parameter stack

locals():

is the same dictionary as globals()

The deprecated global import list is a dictionary with the same lifetime as the instance of this class, initially empty, and filled with all new variables defined by each evaluation of addImport/<import> with a action of '' or 'addNewVarsToInstance'. Use it with care (its use is deprecated) to ensure a clear scope of imports.
All new variables means here all variables which are available in Python globals/locals after the evaluation of the 'import' statement but where not available in Python globals/locals before the evaluation. Hence, if a import add a variable which already existed before it is NOT overwritten. This is different to parameters and a import action "addAllVarsAsParams" which overwrite existing variables with the same name. Overwriting names should be avoid anyway, if possible, to improve readability.

The current parameter stack is a dictionary with a local scope (lifetime). A stack of current parameters exists. Each parameter fills its parameter name to this dictionary overwriting a already existing key. Each addImport/<import> with a action 'allAllVarsLocally' fills all keys which exist after the evaluation in the python global/local context to this list.

Parameter can be a single expressions where the result of the evaluation is used for the value. If the evaluation is a multi statement code, then the result is the value of the variable named "ret" which must be defined by the evaluation. A import is always a multi statement code.

Examples:

<scalarParameter name="p1">4+3</scalarParameter>

Stores the key "p1" with a value of 7 to the current parameter stack. p1 is assigned the single expression value 4+3.

<scalarParameter name="p2">
  a=2
  ret=a+1
</scalarParameter>

Stores the key "p2" with a value of 3 to the current parameter stack. p2 is assigned the value of the variable "ret".

<import action="addAllVarsAsParams">import numpy</import>

Stores the key "numpy" with a struct containing the python numpy module to the current parameter stack. "import numpy" creates a single python variable "numpy" which is stored in the parameter stack.

<anyParameter name="numpy">import numpy as ret</anyParameter>

Stores the key "numpy" with a struct containing the python numpy module to the current parameter stack. "import numpy as ret" import the python numpy module as the name "ret" which is used by a multi statement code as the value of the parameter name "numpy"

<import action="addAllVarsAsParams">from json import *</import>

Stores all objects provided by the python module "json" with its name in to the current parameter stack. "from json import *" creates for each object in side of json a variable name which is stored in the parameter stack.

<import action="addAllVarsAsParams">
  aa=9
  bb=aa+3
  cc=7
</import>

Stores the keys "aa", "bb" and "cc" with the values 9, 12 and 8 to the current parameter stack. All created variables are stored in the parameter stack.

<import action="addAllVarsAsParams">
  def localScope():
    global bb
    aa=9
    bb=aa+3
    cc=7
  localScope()
  del localScope
</import>

Stores the only the key "bb" with the values 12 to the current parameter stack. All variables inside the function localScope have a local scope to this function except the explicitly set global variable "bb". Even the global "localScope" is deleted again, after being called. Hence after the evaluation only the global variable "bb" exists and is added to the current parameter stack.

Note than you can store functions (function pointers) using import and also using anyParameter but such functions cannot access python global variables defined using other parameters since python globals() is defined at function define time and keeps the same regardless of where the function is called. See Python documentation. Hence, pass all required data for such functions via the function parameter list.

The python module mbxmlutils has a dictionary named "staticData" which can be used to store values for the lifetime of the program.

Storing data for the lifetime of the instance of this class is, except the deprecated "addNewVarsToInstance" action, not possible by design for now.

7 Symbolic Functions

The expression evaluators (octave and python) also support symbolic functions known by the symbolic framework of fmatvec. The following table lists all known fmatvec operators and functions of its symbolic framework and its corresponding operators and functions in octave and python. In octave these are impelmented using SWIG and in python the sympy package is used. Some of the operators and functions can also operate on vector arguments.

7.1 Octave Symbolic Functions

As noted above, symbolic functions are implemented in octave using SWIG. Hence, a symbolic scalar is a octave SWIG object. Symbolic vectors and matrices are usual octave vector and matrices with a element data type of octave SWIG object.

7.2 Python Symbolic Functions

As noted above, symbolic functions are used in the python evaluator using the python sympy module. The full power of sympy can be used, however, the resulting symbolic expression passed back to the evaluator can only contain a limited set of symbolic functions. See the above table.

Since the none symbolic part of the python evaluator is based on numpy for vector and matrix representation also symbolic vectors and matrices are based on numpy: a symblic input vector/matrix to the evaluator is a 1D/2D numpy array of dtype=object (each element contains a scalar sympy expression). A vector/matrix output of the evaluator can, however, be of type python list, numpy array or sympy matrix for convenience. Please note that the helper functions in the mbxmlutils module also output vector/matrix data as a numpy array: either of dtype=float for pure numeric data or of dtype=object (with scalar sympy expressions) for mixed or pure symbolic data.

8 Embeding

Using the <pv:Embed> element, where the prefix pv is mapped to the namespace-uri http://www.mbsim-env.de/MBXMLUtils it is possible to embed a XML element multiple times. The full valid example syntax for this element is:

<pv:Embed href="file.xml" count="2+a" counterName="n" onlyif="n!=2"/>

or

<pv:Embed count="2+a" counterName="n" onlyif="n!=2">
  <any_element_with_childs/>
</pv:Embed>

This will substitute the <pv:Embed> element in the current context 2+a times with the element defined in the file file.xml or with <any_element_with_childs>. The insert elements have access to the global parameters, see the next paragraph how to extend these parameters. Moreover, the insert elements have access to a parameter named n which counts from 1 to 2+a (or from 0 to 2+a-1 for 0-based evaluators) and to a parameter named n_count with the value of the count attibute (2+a). The new element is only insert if the octave expression defined by the attribute onlyif evaluates to 1 (true). If the attribute onlyif is not given it is allways 1 (true).
The attributes count and counterName must be given both or none of them. If none are given, then count is 1 and counterName is not used.

counterName cannot depend on any parameters. count can depend on any parameter defined on a higher level. onlyif can depend on any parameter defined on a higher level and on the couterName. All parameters and all elements of the embedded content can depend on any parameter defined on a higher level and on the counterName. href and parameterHref can depend on any parameter define on a higher level but not on counterName.

The first child element of <pv:Embed> can be the element <pv:localParameter> which has one child element <p:parameter> OR a attribute named href. In this case the global parameters are expanded by the parameters given by the element <p:parameter> or in the file given by href. If a parameter already exist then the parameter is overwritten.

<pv:Embed count="2+a" counterName="n" onlyif="n!=2">
  <p:Parameter>
    <p:scalarParameter name="h1">0.5</p:scalarParameter>
    <p:scalarParameter name="h2">h1</p:scalarParameter>
  </p:Parameter>
  <any_element_with_childs/>
</pv:Embed>

9 Measurements

The following subsections show all defined measurements.

The column "Unit Name" in the tables is the name of the unit and the column "Conversion to SI Unit" is a expression which converts a value of this unit to the SI unit.

The highlighted row shows the SI unit of this measurement which always has a conversion of "value".

acceleration

amount

angle

area

bulkModulus

current

damping

density

dynamicViscosity

flow

force

illumination

inertia

kinematicViscosity

length

mass

nounit

pressure

stiffness

temperature

time

torque

velocity

volume