Introduction

This manual describes the format and structure of the OOFEM text input file in detail. An input file can be prepared in any text editor, or generated by a conversion program or an FEM pre-processor.

Some parts of this manual apply only to the parallel-enabled build of the code. Attributes that exist only in that build are enclosed in angle brackets, \(\langle\ \rangle\), and the sections describing them say so explicitly.

The parallel model

The parallel model is based on domain decomposition. In this mode a set of input files must be provided, one per process and its related domain partition. Such a file is called a partition input file.

The name of a partition input file has two parts separated by a full stop: a user-defined base name, and a partition name, which is the rank number of the corresponding partition. Partitions are numbered from zero, and all partition input files must share the same base name.

The parallel version requires a unique global numbering of dof managers (nodes) and elements; the global numbering is what links the partitions together. Dof managers, and optionally elements, on inter-partition boundaries must be marked explicitly so that the different kinds of relation to their remote counterparts can be distinguished — see Parallel mode and Parallel mode.

Running the code

The program is executed by typing

oofem [option [parameter]] ...

on the command line, with the following options:

-v

Print the OOFEM version.

-f path

Path to the OOFEM input file. If not present, the program reads this parameter interactively.

In parallel mode, give only the base name of the input file; the partition name is appended automatically. The partition name is not appended to the output file name given in the output file record (see Output file record).

-r int

Restart the analysis from the given solution step. The corresponding context file (*.osf) must exist.

-rn

Turn on equation renumbering. Default is off.

-ar int

Restart an adaptive computation from the given solution step. Requires the corresponding context file (*.osf) and domain input file (*.din) to exist. The domain input file describes the new mesh; its syntax is identical to that of the input file, except that it contains no output file record, job description record or analysis record.

-l int

Set the threshold for log messages: 0 errors, 1 warnings, 2 relevant, 3 info, 4 debug.

-qo path

Redirect the standard output stream (stdout) to the given file.

-qe path

Redirect the standard error stream (stderr) to the given file.

-c

Force the creation of a context file for each solution step.

-t int

Number of threads to use. Requires a build with OpenMP support.

-p

Run in parallel mode using MPI. Requires a build with MPI support.

-m

Show solution status monitor output, redirecting standard output to files (oofem.stdout and oofem.stderr by default; use -qo and -qe to override).

The parallel version uses the MPI (Message Passing Interface) standard for message passing. To run OOFEM in parallel (the -p flag), you need to know how MPI jobs are executed or scheduled on your system. With the MPICH implementation of MPI, and many others, the following command starts a run on eight processors:

mpirun -np 8 oofem -p program_options

Syntax and general rules

An input file is composed of records. In the current implementation each record occupies one line. The order of the records is compulsory:

1. output file record — Output file record,

2. job description record — Job description record,

3. analysis record — Analysis record,

4. domain record — Domain record,

5. output manager record — Output manager record,

6. components size record — Components size record,

7. node record(s) — Dof manager records,

8. element record(s) — Element records,

9. set record(s) — Set records,

10. cross section record(s) — Cross section records,

11. material type record(s) — Material type records,

12. nonlocal barrier record(s) — Nonlocal barrier records,

13. load and boundary condition record(s) — Load and boundary condition records,

14. initial condition record(s) — Initial condition records,

15. time function record(s) — (Time) function records,

16. optional XFEM manager and associated record(s) — XFEM manager and associated records.

Comments, continuation lines and includes

A line beginning with # is ignored by the parser and can be used as a comment.

A long record can be split over several lines by ending each intermediate line with the continuation character \. Another file can be pulled in with the @include directive:

@include "mesh.in"

Records, keywords and attributes

A record consists of a record keyword followed by one or more attributes. Each attribute is identified by its own keyword, which may be followed by one or more values; some attributes have no value at all. The order of attributes within a record is arbitrary. Keywords and values are separated by one or more spaces.

Sometimes the record keyword itself is variable, taking one of a restricted set of values. The element record, for instance, describes a particular element and its record keyword determines the element type. Such a keyword is called an entity keyword, and the possible substitutions for it are set in a Typewriter font. Where some attributes are specific to a particular entity keyword, the general format of the record is described first and the entity-specific attributes separately; the attributes accepted by the record are then the union of the two.

# nodal records
Node 1 coords 3 0. 0. 0.
Node 2 coords 3 0. 0. 2. dofidmask 3 1 2 3
# element record
Truss2d 1 nodes 2 1 2 crossSect 1

Attribute types

Every attribute value has a type, which fixes its size and layout. Throughout this manual an attribute is written as keyword (type), where type is one of the following.

in — integer number.

val1 25

rn — real number.

val2 -0.234e-3

ch — character. Usually the abbreviation of an unknown type: d for displacement, t for temperature, and so on.

val3 t

ia — integer array, written as size val(1) ... val(size), where all entries are integers separated by one or more spaces. For the array attribute nodes\(=\{1,4,23\}\):

nodes 3 1 4 23

ra — real array, written as size val(1) ... val(size), where size is an integer and the values are reals separated by one or more spaces. For the array attribute coords\(=\{1.0,2.0,3.0\}\):

coords 3 1.0 2.0 3.0

rm — real matrix, written as rows columns {val(1,1) val(1,2) ...; val(2,1) ...}, where rows and columns are integers and the values are reals. Columns are separated by a space or a comma, rows by a semicolon. For the matrix attribute \(\texttt{mat1}=\left[\begin{array}{ccc}1.0&-1.0&0.0\\2.0&2.5&5.0\end{array}\right]\):

mat1 2 3 {1.0 -1.0 0.0; 2.0 2.5 5.0}

dc — dictionary. A dictionary consists of pairs, each pair having a single-character key and an associated real value. It is written as size key(1) val(1) ... key(size) val(size), where size is an integer, the keys are single characters, and the values are reals separated by one or more spaces.

dict1 2 a 1.0 v 0.0

rl — range list, representing a list of integer values. The syntax is { number1 .. numberN (start1 end1) (start2 end2) } and the enclosing braces are compulsory. Individual values are given as plain numbers. A range, that is every number from startI to endI inclusive, is given as a pair enclosed in parentheses. Any number of ranges and single values may be combined.

range1 { 1 7 8 (10 20) (25 30) }

et — entity type, for example a finite element type. The possible values are listed in the section describing the record.

s — character string, which must be enclosed in double quotes.

string1 "string example"

expr — function expression, which must be enclosed in double quotes. It can be a plain value, a simple expression enclosed in $ characters, or a reference to a function record written as @ followed by the record number. A simple expression is evaluated by the internal parser and represents a mathematical expression in certain variables; the variable names and their meaning are given in the section describing the record. The usual arithmetic operators -, +, * and / are supported, and their evaluation order is respected and can be changed with parentheses. The built-in functions sqrt, sin, cos, tan, atan, asin and acos must be written in lower case with their argument in parentheses.

expr1 "2.0"
expr2 "$2.0*sin(t)/3.0$"
expr3 "@2"

Notation used in this manual

Each record is documented by a Record syntax block listing the record keyword and all of its attributes, followed by a Parameters list explaining them. The syntax blocks use the following conventions.

RecordKeyword

A record keyword, set in bold. Where it is an entity keyword, the possible substitutions are listed in the section describing the record.

keyword (type)

A mandatory attribute and its type.

[keyword (type)]

An optional attribute, marked by the enclosing brackets [ ]. Omitting it selects the default behaviour, which is stated in the parameter description. Some optional attributes add information or a property rather than replacing a default — an applied nodal load, for example.

[keyword (…)]

An attribute whose type is given as ... is not a single value but a group of attributes documented in a separate section, to which the parameter description links. sparselinsolverparams (see Sparse linear solver parameters) is the most common example.

< … >

Angle brackets around an attribute mark it as available only in the parallel build of OOFEM; it does not exist in the sequential build. Angle brackets containing ver. and a number, as in <ver. 1.6>, state the OOFEM version from which the record or attribute is available.

keyword^M

An attribute that may be given per meta-step rather than once for the whole analysis. See Analysis record.

Every record is presented in a block like the one below. Parameter names are set in a monospace font throughout the manual; in running text they also carry a light background, so that a keyword is never mistaken for an ordinary word.

As an example, consider this record description:

Record syntax

Particle num (in) color (in) mass (rn) coords (ra) name (s)

A properly formatted input record matching it is:

Particle 2 color 5 mass 0.18 coords 3 0.0 1.0 2.0 name "P1_36"