# MBXMLUtils - XML Documentation

XML-Namespace: http://www.mbsim-env.de/MBXMLUtils

Contents

- 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

Icon | Description
--- | ---
<element> | A XML element of name 'element'
attrName | A XML attribute of name 'attrName'
namespace | A XML namespace of name 'namespace'
type | A XML element or attribute type of name 'type'

# 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`:

Element Name | Substituted Element Name
--- | ---
`Object1` | `Object1`
`myname_3` | `myname_3`
`body{n+6}` | `body8`
`Obj_{n+4}_{if n==2; ret=3; else ret=6; end}` | `Obj_6_3`

# 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>
    </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: it imports submodules, adds to the search path or something else.

# 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.

## 6.2 Python Expression Evaluator

Each evaluation is done in a python context with:

python globals:
  set to python __builtins__ merged with the "imports" and merged with the "current parameters"
python locals:
  is the same dictionary as pyhton globals

Where "imports" is a dictionary with the same lifetime of this class, initially empty, and filled with all new variables defined by each evaluation of `addImport`/`<import>`, see below for details. And "current parameters" are all parameters of the current parameter stack.

If the evaluation is a single expressions, then the result of the evaluation is the result of this expression. If the evaluation is not a single expressions, then the result is the value of the variable named "ret" which must be defined by the evaluation.

`addImport`/`<import>` adds all new variables defined by the evaluation to the "imports": each variable which is in the list of global(=local) variables after the import evaluation, but was not in the list of global(=local) variables before the evaluation, is added to the import list. This import list is then used for all successive evaluations.

# 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.

fmatvec Operator/Function | Octave Operator/Function | Python Operator/Function
--- | --- | ---
`a+b` | `a+b` | `a+b`
`a-b` | `a-b` | `a-b`
`a*b` | `a*b` | `a*b`
`a/b` | `a/b` | `a/b`
`pow(a,b)` | `power(a,b)` | `sympy.Pow(a,b)`
`log(x)` | `log(x)` | `sympy.log(x)`
`sqrt(x)` | `sqrt(x)` | `sympy.sqrt(x)`
`-x` | `-x` | `-x`
`sin(x)` | `sin(x)` | `sympy.sin(x)`
`cos(x)` | `cos(x)` | `sympy.cos(x)`
`tan(x)` | `tan(x)` | `sympy.tan(x)`
`sinh(x)` | `sinh(x)` | `sympy.sinh(x)`
`cosh(x)` | `cosh(x)` | `sympy.cosh(x)`
`tanh(x)` | `tanh(x)` | `sympy.tanh(x)`
`asin(x)` | `asin(x)` | `sympy.asin(x)`
`acos(x)` | `acos(x)` | `sympy.acos(x)`
`atan(x)` | `atan(x)` | `sympy.atan(x)`
`atan2(y,x)` | `atan2(y,x)` | `sympy.atan2(y,x)`
`asinh(x)` | `asinh(x)` | `sympy.asinh(x)`
`acosh(x)` | `acosh(x)` | `sympy.acosh(x)`
`atanh(x)` | `atanh(x)` | `sympy.atanh(x)`
`exp(x)` | `exp(x)` | `sympy.exp(x)`
`sign(x)` | `sign(x)` | `sympy.sign(x)`
`heaviside(x)` | `heaviside(x)` | `sympy.Heaviside(x)`
`abs(x)` | `abs(x)` | `sympy.Abs(x)`
`min(a,b)` | `min([a;b])`[3] | `sympy.Min(a,b)`[1]
`max(a,b)` | `max([a;b])`[3] | `sympy.Max(a,b)`[1]
`condition(c,gt,le)` | `condition(c,gt,le)` | `sympy.Piecewise((gt, c>0), (le, True))`[1][2]

## 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 pyhton 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`

Unit Name | Conversion to SI Unit
--- | ---
`m/s^2` | `value`

## `amount`

Unit Name | Conversion to SI Unit
--- | ---
`mol` | `value`

## `angle`

Unit Name | Conversion to SI Unit
--- | ---
`rad` | `value`
`degree` | `value/360*2*3.141592653589793238462643383279502884`

## `area`

Unit Name | Conversion to SI Unit
--- | ---
`mum^2` | `value*1e-6**2`
`mm^2` | `value*1e-3**2`
`cm^2` | `value*1e-2**2`
`dm^2` | `value*1e-1**2`
`m^2` | `value`
`ar^2` | `value*1e1**2`
`ha` | `value*1e2**2`
`km^2` | `value*1e3**2`

## `bulkModulus`

Unit Name | Conversion to SI Unit
--- | ---
`N/m^2` | `value`
`N/mm^2` | `value*1/1e-3**2`

## `current`

Unit Name | Conversion to SI Unit
--- | ---
`A` | `value`

## `damping`

Unit Name | Conversion to SI Unit
--- | ---
`N*s/m` | `value`

## `density`

Unit Name | Conversion to SI Unit
--- | ---
`kg/m^3` | `value`
`g/cm^3` | `value*1e-3/1e-2**3`
`t/m^3` | `value*1e3/1**3`

## `dynamicViscosity`

Unit Name | Conversion to SI Unit
--- | ---
`mPa*s` | `value*1e-3*1`
`Pa*s` | `value`

## `flow`

Unit Name | Conversion to SI Unit
--- | ---
`mm^3/s` | `value*1e-3**3/1`
`m^3/s` | `value`
`l/s` | `value*1e-1**3/1`
`l/min` | `value*1e-1**3/60`

## `force`

Unit Name | Conversion to SI Unit
--- | ---
`mN` | `value*1e-3`
`N` | `value`
`kN` | `value*1e3`

## `illumination`

Unit Name | Conversion to SI Unit
--- | ---
`cd` | `value`

## `inertia`

Unit Name | Conversion to SI Unit
--- | ---
`kg*m^2` | `value`
`kg*mm^2` | `value*1*1e-3**2`
`g*mm^2` | `value*1e-3*1e-3**2`

## `kinematicViscosity`

Unit Name | Conversion to SI Unit
--- | ---
`m^2/s` | `value`
`mm^2/s` | `value*1e-3**2/1`

## `length`

Unit Name | Conversion to SI Unit
--- | ---
`mum` | `value*1e-6`
`mm` | `value*1e-3`
`cm` | `value*1e-2`
`dm` | `value*1e-1`
`m` | `value`
`km` | `value*1e3`

## `mass`

Unit Name | Conversion to SI Unit
--- | ---
`mg` | `value*1e-6`
`g` | `value*1e-3`
`kg` | `value`
`t` | `value*1e3`

## `nounit`

Unit Name | Conversion to SI Unit
--- | ---
`` | `value`
`-` | `value`
`%` | `value/100`

## `pressure`

Unit Name | Conversion to SI Unit
--- | ---
`mPa` | `value*1e-3`
`Pa` | `value`
`mbar` | `value*1e2`
`bar` | `value*1e5`

## `stiffness`

Unit Name | Conversion to SI Unit
--- | ---
`N/m` | `value`
`N/mm` | `value*1/1e-3`

## `temperature`

Unit Name | Conversion to SI Unit
--- | ---
`K` | `value`
`degC` | `value+273.16`
`degF` | `(value+459.67)*5/9`

## `time`

Unit Name | Conversion to SI Unit
--- | ---
`mus` | `value*1e-6`
`ms` | `value*1e-3`
`s` | `value`
`sec` | `value`
`min` | `value*60`
`h` | `value*3600`
`d` | `value*86400`

## `torque`

Unit Name | Conversion to SI Unit
--- | ---
`N*cm` | `value*1e-2`
`N*m` | `value`

## `velocity`

Unit Name | Conversion to SI Unit
--- | ---
`m/s` | `value`
`km/h` | `value*1e3/3600`

## `volume`

Unit Name | Conversion to SI Unit
--- | ---
`mum^3` | `value*1e-6**3`
`mm^3` | `value*1e-3**3`
`cm^3` | `value*1e-2**3`
`dm^3` | `value*1e-1**3`
`l` | `value*1e-1**3`
`m^3` | `value`
`km^3` | `value*1e3**3`

Generated with MBXMLUtils on 2024-09-11T23:48:32Z