# User Guide

For information on how to install PyFR see Installation.

## Running PyFR

PyFR 2.0.3 uses three distinct file formats:

`.ini`

— configuration file`.pyfrm`

— mesh file`.pyfrs`

— solution file

The following commands are available from the `pyfr`

program:

`pyfr import`

— convert a Gmsh .msh file into a PyFR .pyfrm file.Example:

pyfr import mesh.msh mesh.pyfrm

`pyfr partition`

— partition or repartition an existing mesh and associated solution files.Example:

pyfr partition 2 mesh.pyfrm solution.pyfrs outdir/

Here, the newly partitioned mesh and solution are placed into the directory outdir. Multiple solutions can be provided. Time-average files can also be partitioned, too.

For mixed grids one must include the

`-e`

flag followed by weights for each element type, or the`balanced`

argument. Further details can be found in the performance guide.`pyfr run`

— start a new PyFR simulation. Example:pyfr run mesh.pyfrm configuration.ini

`pyfr restart`

— restart a PyFR simulation from an existing solution file. Example:pyfr restart mesh.pyfrm solution.pyfrs

It is also possible to restart with a different configuration file. Example:

pyfr restart mesh.pyfrm solution.pyfrs configuration.ini

`pyfr export`

— convert a PyFR`.pyfrs`

file into an unstructured VTK`.vtu`

or`.pvtu`

file. If a`-k`

flag is provided with an integer argument then`.pyfrs`

elements are converted to high-order VTK cells which are exported, where the order of the VTK cells is equal to the value of the integer argument. Example:pyfr export -k 4 mesh.pyfrm solution.pyfrs solution.vtu

If a

`-d`

flag is provided with an integer argument then`.pyfrs`

elements are subdivided into linear VTK cells which are exported, where the number of sub-divisions is equal to the value of the integer argument. Example:pyfr export -d 4 mesh.pyfrm solution.pyfrs solution.vtu

If no flags are provided then

`.pyfrs`

elements are converted to high-order VTK cells which are exported, where the order of the cells is equal to the order of the solution data in the`.pyfrs`

file.By default all of the fields in the

`.pyfrs`

file will be exported. If only a specific field is desired this can be specified with the`-f`

flag; for example`-f density -f velocity`

will only export the*density*and*velocity*fields.

PyFR can be run in parallel. To do so prefix `pyfr`

with
`mpiexec -n <cores/devices>`

. Note that the mesh must be
pre-partitioned, and the number of cores or devices must be equal to
the number of partitions.

## Configuration File (.ini)

The .ini configuration file parameterises the simulation. It is written
in the INI format.
Parameters are grouped into sections. The roles of each section and
their associated parameters are described below. Note that both `;`

and
`#`

may be used as comment characters. Additionally, all parameter
values support environment variable expansion.

### Backends

These sections detail how the solver will be configured for a range of different hardware platforms. If a hardware specific backend section is omitted, then PyFR will fall back to built-in default settings.

### Systems

These sections setup and control the physical system being solved, as well as charateristics of the spatial and temporal schemes to be used.

### Boundary and Initial Conditions

These sections allow users to set the boundary and initial conditions of calculations.

### Nodal Point Sets

Solution point sets must be specified for each element type that is used and flux point sets must be specified for each interface type that is used. If anti-aliasing is enabled then quadrature point sets for each element and interface type that is used must also be specified. For example, a 3D mesh comprised only of prisms requires a solution point set for prism elements and flux point sets for quadrilateral and triangular interfaces.

- [solver-interfaces-line{-mg-p
*order*}] - [solver-interfaces-quad{-mg-p
*order*}] - [solver-interfaces-tri{-mg-p
*order*}] - [solver-elements-quad{-mg-p
*order*}] - [solver-elements-tri{-mg-p
*order*}] - [solver-elements-hex{-mg-p
*order*}] - [solver-elements-tet{-mg-p
*order*}] - [solver-elements-pri{-mg-p
*order*}] - [solver-elements-pyr{-mg-p
*order*}]

### Plugins

Plugins allow for powerful additional functionality to be swapped
in and out. There are two classes of plugin available; solution
plugins which are prefixed by `soln-`

and solver plugins which
are prefixed by `solver-`

. It is possible to create multiple
instances of the same solution plugin by appending a suffix, for
example:

```
[soln-plugin-writer]
...
[soln-plugin-writer-2]
...
[soln-plugin-writer-three]
...
```

Certain plugins also expose functionality via a CLI, which can be invoked independently of a PyFR run.

#### Solution Plugins

#### Solver Plugins

#### Regions

Certain plugins are capable of performing operations on a subset of the
elements inside the domain. One means of constructing these element
subsets is through parameterised regions. Note that an element is
considered part of a region if *any* of its nodes are found to be
contained within the region. Supported regions:

- Rectangular cuboid
`box(x0, x1)`

A rectangular cuboid defined by two diametrically opposed vertices. Valid in both 2D and 3D.

- Conical frustum
`conical_frustum(x0, x1, r0, r1)`

A conical frustum whose end caps are at

*x0*and*x1*with radii*r0*and*r1*, respectively. Only valid in 3D.- Cone
`cone(x0, x1, r)`

A cone of radius

*r*whose centre-line is defined by*x0*and*x1*. Equivalent to`conical_frustum(x0, x1, r, 0)`

. Only valid in 3D.- Cylinder
`cylinder(x0, x1, r)`

A circular cylinder of radius

*r*whose centre-line is defined by*x0*and*x1*. Equivalent to`conical_frustum(x0, x1, r, r)`

. Only valid in 3D.- Cartesian ellipsoid
`ellipsoid(x0, a, b, c)`

An ellipsoid centred at

*x0*with Cartesian coordinate axes whose extents in the*x*,*y*, and*z*directions are given by*a*,*b*, and*c*, respectively. Only valid in 3D.- Sphere
`sphere(x0, r)`

A sphere centred at

*x0*with a radius of*r*. Equivalent to`ellipsoid(x0, r, r, r)`

. Only valid in 3D.

All region shapes also support rotation. In 2D this is accomplished by
passing a trailing rot=angle argument where angle is a rotation
angle in degrees; for example `box((-5, 2), (2, 0), rot=30)`

.
In 3D the syntax is rot=(phi, theta, psi) and corresponds to a
sequence of Euler angles in the so-called *ZYX convention*. Region
expressions can also be added and subtracted together arbitrarily.
For example
`box((-10, -10, -10), (10, 10, 10)) - sphere((0, 0, 0), 3)`

will
result in a cube-shaped region with a sphere cut out of the middle.

### Additional Information

The INI file format is very versatile. A feature that can be useful in defining initial conditions is the substitution feature and this is demonstrated in the [soln-plugin-integrate] plugin example.

To prevent situations where you have solutions files for unknown
configurations, the contents of the `.ini`

file are added as an attribute
to `.pyfrs`

files. These files use the HDF5 format and can be
straightforwardly probed with tools such as h5dump.

In several places within the `.ini`

file expressions may be used. As well as
the constant `pi`

, expressions containing the following functions are
supported:

`+, -, *, /`

— basic arithmetic`sin, cos, tan`

— basic trigonometric functions (radians)`asin, acos, atan, atan2`

— inverse trigonometric functions`exp, log`

— exponential and the natural logarithm`tanh`

— hyperbolic tangent`pow`

— power, note`**`

is not supported`sqrt`

— square root`abs`

— absolute value`min, max`

— two variable minimum and maximum functions, arguments can be arrays