ofeli library

File Formats

OFELI files use the XML syntax. They are valid XML documents. Input files can be given separately or gathered in one or more files.

A typical set of header lines of OFELI XML files is the following lines:

<?xml version="1.0" encoding="ISO-8859-1" ?>
  <OFELI_File>
  <info>
    <title></title>
    <date></date>
    <author></author>
  </info>
   ...
   ...
  </OFELI_File>

Tags title, date and author can be filled in order to keep useful information for a user.
After the preamble given by the element <info>, the XML file can contain any of the following elements in any order:

Project	To describe project data: parameters, input and output files, ... This information enables constructing the class IPF.
Domain	To describe domain geometry
Mesh	To describe mesh data
Prescription	To describe prescription of boundary conditions, body and boundary forces, ...
Material	To describe material data
Field	To describe input and output field data
Function	To describe a tabulated function

Element: Project

The element Project enables giving various parameters to control program execution as well as various file names. All acquired data are used to construct the class IPF. When invoking this element, one must supply the attribute that gives the projects name as follows:

<Project name="project_name">
  ...
  ...
</Project>

The element Project has a large choice of subelements. Each subelement is a parameter that can be retrieved by calling a member function of class IPF. These parameters either have a predefined name, e.g. max_time that clearly chooses the maximal time for computations and whose is retrieved in the class IPF by the member function getMaxTime, or by a generic parameter for which a user can define a label. For instance, in the line

     <parameter label="deltat" value="0.1"&/>

the read parameter is retrieved by the code line

     dt = ipf.getDouble("deltat");

or equivalently

     ipf.get("deltat",dt);

where ipf is an instance of class IPF.

The following table describes the list of parameters in the Prescription file:

verbose	Level for information output. Typically, the integer number must be between 1 and 10. Its default value is 1
output	Level for solution output. Its default value is 0
save	Level for solution saving in file. Its default value is 0
plot	An integer that defines a level for solution saving in plot file. Its default value is 0
bc	Flag for boundary condition (Dirichlet) handling. 1: Boundary condition vector is described in a prescription file (Default value) 2: Boundary condition vector is in a field file
bf	Flag for body force handling. 1: Body force is described in a prescription file (Default value) 2: Body force vector is in a field file
sf	Flag for surface force (Neumann boundary condition) handling. 1: Surface force vector in a prescription file (Default value) 2: Read surface force vector in a field file
init	Flag for initial condition handling. 1: Initial solution in a prescription file (Default value) 2: Read initial solution in a field file
max_time	A real number that defines maximal time for a time dependent calculation. Its default value is 1.0
time_step	Time step for a time dependent calculation. Its default value is 0.1
nb_steps	Number of time steps for a time dependent calculation. Its default value is 10
nb_iter	Maximum number of iterations for an iterative scheme. Its default value is 100
tolerance	Tolerance for convergence for an iterative scheme. Its default value is 1.e-6
integer	An integer parameter that can be retrieved by the member function getIntPar(i) where i is the rank of appearance of this keyword. Up to 10 integer parameters can be contained in the file. This maximal number is defined by the constant MAX_NB_PAR in the OFELI constants
double	A double precision parameter that can be retrieved by the member function getDoublePar(i) where i is the rank of appearance of this keyword. Up to 10 double precision parameters can be contained in the file. This maximal number is defined by the constant MAX_NB_PAR in the OFELI constants
complex	A complex parameter that can be retrieved by the member function getComplexPar(i) where i is the rank of appearance of this keyword. Up to 10 complex parameters can be contained in the file. This maximal number is defined by the constant MAX_NB_PAR in the OFELI constants
mesh_file	Name of file that contains mesh data. The default mesh file name has as extension project_name.m
init_file	Name of file that contains initial data
restart_file	Name of file that contains restarting field file. This file is useful when an iteration process (or time stepping procedure) is used and the programs stops to restart later
bc_file	Name of file that contains (Dirichlet) boundary condition data
bf_file	Name of file that contains body force initial data
sf_file	Name of file that contains surface force data
save_file	Name of file that fields to save
plot_file	Name of file that contains fields to plot
data_file	Name of file that contains various data
aux_file	Name of file that contains any other data in any format. Any occurrence of this keyword will define a new file name that can be retrieved through the member function getAuxFile(i) where i is the rank of the appearance of this keyword. Up to 10 occurrences can be contained in the file. This maximal number is defined by the constant MAX_NB_PAR in the OFELI constants
parameter	As explained in the example above, this subelement must contain an option called label that identifies the parameters and then optionally the option value to specify a value. If this option is not present, a value must be given before closing the subelement

Note that the argument of each subelement can be given either through the attribute value or through a value that given between the opening and the closing of the subelement.

Let us give a simple example of XML file using the Project element, where we have used both possibilities of defining subelements.

  <?xml version="1.0" encoding="ISO-8859-1" ?>
  <OFELI_File>
    <info>
      <title>Project file</title>
      <date>August 18, 2008</date>
      <author>R. Touzani</author>
    </info>
    <Project name="beam">
      <mesh_file>beam.m</mesh_file>
      <data_file>beam.pr</data_file>
      <parameter label="d-file">beam.d</parameter>
      <parameter label="density" value="1.2"/>
      <nb_iter>100</nb_iter>
      <tolerance value="1.e-5"></tolerance>
      <verbose>1</verbose>
      <output>1</output>
      <save value="1"/>
    </Project>
  </OFELI_File>

Element: Domain

The element Domain enables defining a domain geometry. At the current stage of development of OFELI, a domain definition is necessary to generate meshes in the 2-D configurations. This element has 2 attributes:

The attribute dim defines the space dimension. Typically, 1, 2 or 3. Its default value is 2.
The attribute nb_dof defines the number of degrees of freedom on any unknown support. For instance, if unknowns are supported by nodes, one can specify that each node supports 2 degrees of freedom for a planar elasticity problem. The default value of this parameter is 1.

An example of use of this element is:

     <Domain dim="2">
       <vertex>  0.   0.   1    0.1</vertex>
       <vertex>  1.   0.   1    0.1</vertex>
       <vertex>  1.   1.   1    0.1</vertex>
       <vertex>  0.   1.   1    0.1</vertex>
       <vertex>  0.5  0.5  2    0.1</vertex>
       <vertex>  0.6  0.5  2    0.1</vertex>
       <line>   1   2   1</line>
       <line>   2   3   1</line>
       <line>   3   4  -2</line>
       <line>   4   1  -2</line>
       <circle> 6   6   5   1</circle>
       <subdomain>   1   1  10</subdomain>
     </Domain>

Let us describe the subelements of element Domain:

vertex	To describe a vertex in the domain
line	To describe a straight line that joins 2 vertices
circle	To describe a circular arc
subdomain	To describe a subdomain with a specific code

The subelement vertex describes a vertex by the following data:
```
   x   y   c   h
```
where x and y are the vertex coordinates, h is the mesh size around the vertex and c is the code to assign to the vertex. This code will be transferred to the vertex once a mesh is generated
The subelement line describes a straight line by the following data:
```
   n1  n2  c
```
where the line goes from vertex n1 to vertex n2 and c is the boundary condition code. This one is assigned to the nodes generated on the line (Dirichlet) if it is positive and its opposite value is assigned to the sides generated on the line (Neumann) if it is negative. Note the line is actually oriented from n1 to n2
The subelement circle describes a circular arc by the following data:
```
   n1  n2  n3  c
```
where the arc goes from vertex n1 to vertex n2. Note that we can have n1=n2 which in this case generates an entire circle. The center of the circle is located at vertex n3. The integer c stands for the code to assign to nodes generated on the line (Dirichlet) if the code is positive and its opposite value is assigned to the to sides generated on the line (Neumann) if it is negative.
The subelement subdomain describes a subdomain by the following data:
```
   n  i  c
```
where n is a line (or arc) that belongs to the boundary of the subdomain, i is the arc orientation. It must be equal to 1 (anti-clockwise) or -1, and c is a code (integer number) to associate to the subdomain

Element: Mesh

The element Mesh enables providing data that describe a finite element mesh. It has 2 optional attributes:

The attribute dim defines the space dimension. Typically, 1, 2 or 3. Its default value is 2.
The attribute nb_dof defines the number of degrees of freedom on any unknown support. For instance, if unknowns are supported by nodes, one can specify that each node supports 2 degrees of freedom for a planar elasticity problem. The default value of this parameter is 1.

An example of use of this element is:

     <Mesh dim="3" nb_dof="2">
       ...
       ...
     </Mesh>

This element has the following subelements:

Nodes	To describe nodes
Elements	To describe elements
Sides	To describe sides
Material	To describe materials for elements

The subelement Nodes enables defining each node data. Typically, it can be used as follows:
```
  <Nodes>
    x1   y1   z1   c1   x2   y2   z2   c2   x3   y3   z3   c3
    x4   y4   z4   c4        ...
    ...
    ...      ...        xn   yn   zn   cn
  </Nodes>
```
More precisely, each node is given by its coordinates. In this example, a 3-D problem requires three coordinates. For a 2-D problem only x and y-coordinates are required. The coordinates are followed by an integer number that describes a code to associate to the node. This code is used to prescribe boundary conditions. It is important to mention that any nonzero code enforces a boundary condition of a given DOF (Degree Of Freedom). By convention, this code is chosen such that it has as many digits as the number of DOF for the node. For instance if the number of DOF of a node is 3, then the code number 231 yields a code 2 for the first DOF, 3 for the second DOF and 1 for the third one.
Another important thing to note is that the nodes are given in a free format one after the other. Moreover, the number of nodes doesn't have to be specified. The parser deduces it from the list size.
The subelement Elements enables defining the finite elements. It has the following attributes:
- The attribute shape specifies the shape of the finite element. It must take one of the following values: line, triangle or tria, quadrilateral or quad, tetrahedron or tetra, and hexahedron or hexa. The default value is line for 1-D, triangle for 2-D and tetrahedron for 3-D.
- The attribute nodes is the number of element nodes. Its default value is 2 for 1-D,3 for 2-D, and 4 for 3-D.
A typical example of subelement Elements is the following:
```
  <Elements shape="triangle" nodes="3">
    1   2   5   1     2   3   5   1
    3   4   5   1     4   1   5   1
  </Elements>
  <Elements shape="quadrilateral" nodes="4">
    2   6   7   3   2
  </Elements>
```
Note that the elements are grouped shape by shape.
More precisely, for each element are given:
- The list of its nodes. Their number is given by the attribute nodes or by its default value.
- An integer number that stands for its code. This code is helpful to specify the material in which lies the element. It can also be used for any other purpose to select lists of elements.
Note that the number of elements doesn't have to be specified. The parser deduces it from the list size.
The subelement Sides enables defining sides (edges in 2-D, faces in 3-D) in a finite element mesh. It has the following attributes:
- The attribute shape specifies the shape of the side. It must take one of the following values: line, triangle or tria, quadrilateral or quad. The default value is line for 2-D and triangle for 3-D.
- The attribute nodes is the number of side nodes. Its default value is 2 for 2-D and 3 for 3-D.
A typical example of subelement Sides is the following:
```
  <Sides shape="line" nodes="2">
    1   2   1     2   3   1
  </Sides>
```
Note that the sides are grouped shape by shape.
More precisely, for each side are given:
- The list of its nodes. Their number is given by the attribute nodes or by its default value.
- An integer number that stands for its code. This code plays the same role as for nodes.
Note that the number of sides doesn't need be specified. The parser deduces it from the list size.
The subelement Material enables attributing a material to each element code. Element codes are given as integers in the Elements section. If no material is associated to a code, the library assigns a so-called Generic material with default physical properties. This is to be used for testing purposes. For a realistic use of the library, each material is defined through its properties by an XML file. For instance, the material Iron is defined in the file Iron.md. Depending on the stage of development of the library, number of material files are already present. The element <Material> enables defining a user's material.
A typical example of subelement Material is the following:
```
  <Material>
    1   Rubber
    5   Copper
   </Material>
```
More precisely, each material is given by an integer that is the code and a string that is the material name. Either the material file exists in the given list of OFELI materials (here files Rubber.md and Copper.md), or the user provides in his own directory the required material file.

Element: Prescription

This element encloses information on conditions to prescribe for the numerical solution by the OFELI library. We mean here by prescription, enforcement of boundary conditions (Dirichlet), Boundary forces (Neumann boundary conditions, Body forces (right-hand side of equations, initial condition, ... To each type of prescription corresponds a subelement. Moreover, prescription of variable (time and/or space dependent) conditions are allowable through algebraic equations.
The element Prescription doesn't have any attribute. It has the following subelements:

BoundaryCondition	To prescribe (essential or Dirichlet) boundary conditions
BodyForce	To prescribe body forces or sources, ...
Source	Identical to BodyForce
BoundaryForce	To prescribe boundary forces (Neumann boundary conditions), like tractions, fluxes, ...
Traction	Identical to BoundaryForce
Flux	Identical to BoundaryForce
Initial	To prescribe an initial condition

The subelement BoundaryCondition enables prescribing a Dirichlet boundary condition. A typical example of its use is:
```
 <BoundaryCondition code="1" dof="2">x*exp(t)</BoundaryCondition>
```
More precisely, this subelement has the following attributes:
- The attribute code specifies the code for which the boundary condition is assigned. For example, if the degrees of freedom are supported by nodes, this code is the one associated to nodes.
- The attribute dof specifies the degree of freedom index to which the boundary condition is assigned. If this attribute is not present, the condition is enforced to all dofs'.
The subelement BodyForce enables prescribing the volume right-hand side of the partial differential equation (Domain integral in the variational formulation). Depending on the problem origin, this one can be called Body Force, Load, Source, ... A typical example of its use is:
```
  <BodyForce dof="2">1.0</BodyForce>
```
As it can be noticed, this subelement works like BoundaryCondition except the attribute code which has no meaning in this context
The subelement Source is exactly identical to BodyForce
The subelement BoundaryForce enables prescribing the surface right-hand side of the partial differential equation (Boundary integral in the variational formulation or Neumann condition). Depending on the problem origin, this one can be called Boundary Force, Traction, Flux, ... A typical example of its use is:
```
  <BoundaryForce code ="5" dof="2">x-y</BoundaryForce>
```
As it can be noticed, this subelement works like BoundaryCondition, The difference being that this condition is generally applied to sides (edges or faces) whereas the Dirichlet boundary condition applies generally to nodes.
The subelement Traction is exactly identical to BoundaryForce
The subelement Flux is exactly identical to BoundaryForce
The subelement Initial enables prescribing an initial condition for a time-dependent problem or an initial solution for an iterative process.
A typical example of its use is:
```
  <Initial dof="1">(1.0+sin(x))*exp(-t)</Initial>
```
As it can be noticed, this subelement works like BodyForce for instance.

Element: Material

Material data are stored in specific XML files. Each file corresponds to a given material. The OFELI library contains a collection of material files that will be enriched in the forthcoming releases.
In OFELI, the material named Mat is described in the XML file: Mat.md

Let us give as example the material file for the material Copper. Here is the listing of the file Copper.md the

   <?xml version="1.0" encoding="ISO-8859-1" ?>
     <OFELI_File>
       <info>
         <title>Material data for Copper</title>
         <date></date>
         <author></author>
       </info>
       <Material name="Copper">
         <Density>1.</Density>
         <SpecificHeat>8920.</SpecificHeat>
         <ThermalConductivity>401.</ThermalConductivity>
         <ElectricConductivity>5.9302e07</ElectricConductivity>
         <ElectricResistivity>1.6863e-8</ElectricResistivity>
         <MagneticPermeability>12.566371e-7</MagneticPermeability>
         <PoissonRatio>0.34</PoissonRatio>
         <YoungModulus>15.e10</YoungModulus>
       </Material>
     </OFELI_File>

The structure of this file doesn't need any additional explanation. We shall however give hereafter the list of properties that can be stored in the XML file:

Density	Density of material (Heat and Mass Transfer)
SpecificHeat	Specific Heat (Heat Transfer)
ThermalConductivity	Thermal Conductivity (Heat Transfer)
MeltingTemperature	Melting Temperature (Heat Transfer)
EvaporationTemperature	Evaporation Temperature (Heat Transfer)
ThermalExpansion	Thermal Expansion (Heat and Mass Transfer)
LatentHeatMelting	Latent Heat for Melting (Heat Transfer)
LatentHeatEvaporation	Latent Heat for Evaporation (Heat Transfer)
DielectricConstant	Dielectric Constant (Electromagnetism)
ElectricConductivity	Electric Conductivity (Electromagnetism)
ElectricResistivity	Electric Resistivity: Inverse of Conductivity (Electromagnetism)
MagneticPermeability	Magnetic Permeability (Electromagnetism)
Viscosity	Kinematic Viscosity (Fuid Dynamics)
YoungModulus	Young Modulus (Solid Mechanics)
PoissonRatio	Poisson Ratio (Solid Mechanics)

Element: Field

The element Field is useful to store vectors, such as input vectors, results. We have grouped all these vectors under the term Field. The field file that contains these vectors can be transformed via conversion programs to various file formats for well known free and commercial graphical postprocessors.

Fields can be divided into 3 types depending on the degree of freedom support: Fields can be given by nodes, elements or sides. In addition, in view of handling time-dependent problems, the file can contain as many vectors as necessary, each one corresponding to a given time step.

A typical file containing fields looks like this

  <OFELI_File>
    ... ...
    <Field name="Temperature" type="Node" nb_dof="1">
      <Step time="0.1">
        ... ...
        ... ...
      </Step>
      <Step time="0.2">
        ... ...
        ... ...
      </Step>
    </Field>
    <Field name="Displacement" type="Element" nb_dof="2">
      <Step time="0.1">
        <constant dof="1">1.0</constant>
        <expression dof="2">x*exp(t)</expression>
      </Step>
    </Field>
  </OFELI_File>

More precisely, the element Field has the attributes:

The attribute name specifies the name to give to the field. This attribute is optional.
The attribute type specifies the type of the field. It must take one of the values: Node, Element or Side. The default value is Node.
The attribute nb_dof gives the number of degrees of freedom for one support, e.g. if the type is Node, there are nb_dof values per node. The default value of this attribute is "1"

The element Field has only one subelement: Step
The subelement Step gives the vector entries for the specified value of the attribute time. It owns two subelements:
- The element constant enables assigning a constant value to all vector entries for one given dof or all dofs. It has the attribute dof that can specify the dof to be assigned. By default, all dofs are assigned this constant value
- The element expression enables assigning an algebraic expression that may involve the coordinates x, y, z and the time t, to all vector components for one given dof or all dofs. It has the attribute dof that can specify the dof to be assigned. By default, all dofs are assigned this expression

Element: Function

The element Function defines a tabulated function of one, two or three variables. In order to minimize computational cost, each variable is defined by a uniform partitioning given by its minimal value, its maximal values and the number of grid points.
This element has as unique attribute the name of the function.
A typical usage of this element is:

  <Function name="Density">
    <Variable label="x" nb_pts="5" min="0" max="1"/>
    <Variable label="y" nb_pts="4" min="10" max="12"/>
    <Data>
      1.0   2.0   5.0   7.0
      2.0   3.0   5.0   8.0
      7.0   2.0   5.0   9.0
      0.0   2.0   8.0  10.0
      11.0  20.0  25.0  30.0
    </Data>
  </Function>

Let us describe the subelements of element Function:

Variable	To describe a variable
Data	To give list of function values

The subelement Variable describes a variable. Its attributes are:
- The attribute label gives a name to the variable. This name has no particular usage. Only the order of the variables is important for a function evaluation.
- The attribute nb_pts gives the number of grid points for this variable, i.e. This is the number of grid intervals plus one
- The attribute min gives the minimal value of the variable
- The attribute max gives the maximal value of the variable
The subelement Data gives the function values ordered as follows (This is an example of a function of 2 variables):
```
   val(1,1)   val(1,2)   ...  val(1,n2)
   val(2,1)   val(2,2)   ...  val(2,n2)
   ...
   val(n1,1)  val(n1,2)  ...  val(n1,n2)
```
where n1 and n2 are the number of points for the first and second variable respectively.