XML-Namespace: http://www.mbsim-env.de/MBXMLUtils
| 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' |
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 |
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.
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 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>
<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
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 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>
<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
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.
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 '&', '<' and '>', 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:
Each evaluation is done in a clean octave context with:
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.
Each evaluation is done in a python context with:
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.
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] |
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.
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.
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>
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 |