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, :math:`\langle\ \rangle`, and the sections describing them say so explicitly. .. _parallel-model: 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 :ref:`parallel-dofmanagers` and :ref:`parallel-elements`. .. _running-the-code: Running the code ---------------- The program is executed by typing .. code-block:: none 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 :ref:`OutputFileRecord`). ``-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: .. code-block:: none mpirun -np 8 oofem -p program_options .. _syntax-and-general-rules: 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: #. output file record — :ref:`OutputFileRecord`, #. job description record — :ref:`JobDescriptionRecord`, #. analysis record — :ref:`AnalysisRecord`, #. domain record — :ref:`DomainRecord`, #. output manager record — :ref:`OutputManagerRecord`, #. components size record — :ref:`ComponentsSizeRecord`, #. node record(s) — :ref:`NodeElementSideRecords`, #. element record(s) — :ref:`ElementsRecords`, #. set record(s) — :ref:`SetRecords`, #. cross section record(s) — :ref:`CrossSectionRecords`, #. material type record(s) — :ref:`MaterialTypeRecords`, #. nonlocal barrier record(s) — :ref:`NonlocalBarrierRecords`, #. load and boundary condition record(s) — :ref:`LoadBoundaryInitialConditions`, #. initial condition record(s) — :ref:`InitialConditions`, #. time function record(s) — :ref:`TimeFunctionsRecords`, #. optional XFEM manager and associated record(s) — :ref:`XFEMManagerRecords`. 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: .. code-block:: none @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. .. code-block:: none # 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: Attribute types ~~~~~~~~~~~~~~~ Every attribute value has a type, which fixes its size and layout. Throughout this manual an attribute is written as :elemparam:`keyword{type}`, where *type* is one of the following. **in** — integer number. .. code-block:: none val1 25 **rn** — real number. .. code-block:: none val2 -0.234e-3 **ch** — character. Usually the abbreviation of an unknown type: ``d`` for displacement, ``t`` for temperature, and so on. .. code-block:: none 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``\ :math:`=\{1,4,23\}`: .. code-block:: none 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``\ :math:`=\{1.0,2.0,3.0\}`: .. code-block:: none 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 :math:`\texttt{mat1}=\left[\begin{array}{ccc}1.0&-1.0&0.0\\2.0&2.5&5.0\end{array}\right]`: .. code-block:: none 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. .. code-block:: none 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. .. code-block:: none 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. .. code-block:: none 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. .. code-block:: none expr1 "2.0" expr2 "$2.0*sin(t)/3.0$" expr3 "@2" .. _notation: 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. :descitem:`RecordKeyword` A record keyword, set in bold. Where it is an entity keyword, the possible substitutions are listed in the section describing the record. :elemparam:`keyword{type}` A mandatory attribute and its :ref:`type `. :optelemparam:`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. :optelemparam:`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 :ref:`sparselinsolver`) 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 ````, state the OOFEM version from which the record or attribute is available. ``keyword``\ :sup:`M` An attribute that may be given per meta-step rather than once for the whole analysis. See :ref:`AnalysisRecord`. 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:: :descitem:`Particle` :elemparam:`num{in}` :elemparam:`color{in}` :elemparam:`mass{rn}` :elemparam:`coords{ra}` :elemparam:`name{s}` A properly formatted input record matching it is: .. code-block:: none Particle 2 color 5 mass 0.18 coords 3 0.0 1.0 2.0 name "P1_36"