Writing input files

Getting started

Starting from one of the demos is recommended. Most of the input options used in the demo input files (and most other input options) are explained in Input file sections below.

As a general rule, based on what parts of Ocellaris are most used and best tested, the following options are good starting points for creating your own simulation input files:

  • Use a simple mesh (unit square or cube etc) or load your mesh with the meshio reader, see Mesh.

  • Use the IPCS-A solver. If you are running on only one CPU then consider the Coupled solver (but it lacks some functionality comapred to IPCS-A), see Navier Stokes solver for the full list.

  • Use single phase or the standard algebraic VOF multi phase solver, see BlendedAlgebraicVOF under Multi phase solver for details.

  • Write restart files once in a while to be able to restart your long running simulations should something hang, see Output control for details on this. You should also consider using the orun script to “babysit” your simulations, see orun.py - Run Ocellaris on a HPC with automatic restarts.

  • Write XDMF plot files for visualization in Paraview and similar programs so that you can understand what is happening in your simulation.

File format

Ocellaris uses the YAML format for input files. The input file is divided into separate sections dealing with geometry, boundary conditions, solver parameters etc. The different sections are described below. Multiple demos are provided along with Ocellaris and it is recommended to start with one of the demo input files and use the below documentation as an aid to change the demo input file into one that is describing your specific simulation.

Note that since JSON is a valid subset of YAML, you can also write the input file in JSON format. JSON has no simple support for multi-line strings and comments, so YAML is the format used by the Ocellaris demos and also in the descriptions below.

Common errors

Some errors that are easy to make when writing a YAML input file:

  • Booleans in YAML are written all lower case (true, false) unlike in Python where the first letter is upper case (True, False). It can be easier to use the alternatives on or off so this confusion is avoided.

  • The value 5e-3 is a string in YAML while 5.0e-3 is a float.

  • Indentation is significant, just like in Python

  • Misspellings are not errors!

The input you specify is validated against a schema, but you only get a warning in the top of the Ocellaris simulation log file and no errors since the schema is not guaranteed to be perfect. The input file YSchema file (ocellaris/input_file_schema.yml in the source code) is an approximate representation of all valid and invalid Ocellaris input files and it is not trusted to reject files that it believes are not valid. The warning can still help catching some misspelling errors, but you must read the log file to see them. When performing a new type of simulation it is always strongly recommended to thoroughly read through the start of the log file for warnings from the schema validator and from the many other modules of Ocellaris that will warn you about fishy input.