Simulation classes API

The simulation classes holds the simulation data (velocity, pressure, function spaces, mesh etc) and is also responsible for most utility functionality such as plugins (hooks), logging, reporting, plotting and input file handling.

class ocellaris.Simulation

Bases: object

Represents one Ocellaris simulation. The Simulation class connects the input file, geometry, mesh and more with the solver, results IO and reporting tools

input

An ocellaris.simulation.input.Input object that holds the input from the input file provided by the user

io

An ocellaris.simulation.io.InputOutputHandling object that holds supports writing VTK, XDMF, restart HDF5 files etc

hooks

An ocellaris.simulation.hooks.Hooks object that keeps track of functions that should run at certain times during the simulation

reporting

An ocellaris.simulation.reporting.Reporting object that helps report summary values each time step

log

An ocellaris.simulation.log.Log object that helps with logging messages to screen while the simulation is running

data a dictionary

In a typical simulation the data attribute will contain contents such as:

Name

Value

boundary

boundary_marker

cell_info

connectivity_CC

connectivity_CF

connectivity_FC

constrained_domain

A SubDomain object that reporesents the periodic boundary conditions, or None if no periodic boundary conditions are applied

dirichlet_bcs

A dictionary of lists of boundary conditions {‘u0’: […], ‘p’: […], …}

ds

A measure of the boundaries that has been marked by the boundary conditions

facet_info

g

The acceleration of gravity (vector constant)

mesh

The FEniCS mesh object

neumann_bcs

A dictionary of lists of boundary conditions {‘u0’: […], ‘p’: […], …}

nu

The kinematic viscosity (constant or scalar valued function)

p

The pressure at the current time step

p_hat

The pressure correction used to get to the current time step

rho

The density (constant or scalar valued function)

u, u0, u1, u2

The velocity at the current time stepas a vector and as components

u_conv, u_conv0, u_conv1, u_conv2

The extrapolated convecting velocity at the current time step as a vector and as components

u_star, u_star0, u_star1, u_star2

The predicted velocity at the current time step as a vector and as components

up, up0, up1, up2

The velocity at the previous time step as a vector and as components

upp, upp0, upp1, upp2

The velocity at the previous-previous time step as a vector and as components

Vp

The function space of velocities

Vp

The function space of pressures
flush(force=False)

Flush output files if an appropriate amount of time has passed. This ensures that flush can be called after important output without slowing down the solver too much with disk IO in case of many calls to flush in quick succession

get_data(name)

Return a solver variable if one exists with the given name (p, u0, mesh, …) or a known field function if no solver variable with the given name exists.

Known field functions must be specified (as always) with forward slash separated field name and function name, e.g., “waves/c”

set_mesh(mesh, mesh_facet_regions=None)

Set the computational domain

setup()

Setup the simulation. This creates the .solver object as well as the mesh, boundary conditions, initial condition, function spaces, runtime post-processing probes, program and user defined hooks …

update_mesh_data(connectivity_changed=True)

Some precomputed values must be calculated before the timestepping and updated every time the mesh changes

class ocellaris.simulation.input.Input(simulation, values=None, basepath='')

Bases: dict

Holds the input values provided by the user

ensure_path(path)

Ensures that get_value(path) will succeed.

Returns the object at the given path.

get_input_file_path(file_name)

Serch first relative to the current working dir and then relative to the input file dir

get_output_file_path(path, default_value=<UNDEFINED>)

Get the name of an output file

Automatically prefixes the file name with the output prefix

get_value(path, default_value=<UNDEFINED>, required_type='any', mpi_root_value=False, safe_mode=False, required_length=None)

Get an input value by its path in the input dictionary

Gives an error if there is no default value supplied and the input variable does not exist

Parameters

  • path – a list of path components or the “/” separated path to the variable in the input dictionary

  • default_value – the value to return if the path does not exist in the input dictionary

  • required_type – expected type of the variable. Giving type=”any” does no type checking. Other options are “int”, “float”, “string”, “bool”, “Input”, “list(float)”, “dict(string:any)” etc

  • mpi_root_value – get the value on the root MPI process

  • safe_mode – do not evaluate python expressions “py$ xxx”

Returns

The input value if it exist otherwise the default value

has_path(path)

Checks if there is something (terminal or nested dict) at path

read_yaml(file_name=None, yaml_string=None)

Read the input to an Ocellaris simulation from a YAML formated input file or a YAML formated string. The user will get an error if the input is malformed

set_value(path, value)

Set an input value by its path in the input dictionary

Parameters

  • path – a list of path components or the “/” separated path to the variable in the input dictionary

  • value – the value to set

validate_and_convert(path, value, required_type='any', safe_mode=False, required_length=None)

Verify that the given value has an appropriate type. Returns the value if it is OK, else calls ocellaris_error

NOTE: returns copies of any mutable value type to avoid being able to change the input object by modifying the returned data

class ocellaris.simulation.io.InputOutputHandling(simulation)

Bases: object

This class handles reading and writing the simulation state such as velocity and presure fields. Files for postprocessing (xdmf) are also handled here

add_extra_output_function(function)

The output files (XDMF) normally only contain u, p and potentially rho or c. Other custom fields can be added

add_plotter(func, interval_inp_key, default_interval)

Add a plotting function which produces IO output every timestep

get_persisted_dict(name)

Get dictionary that is persisted across program restarts by pickling the data when saving HDF5 restart files.

Only basic data types in the dictionary are persisted. Such data types are ints, floats, strings, booleans and containers such as lists, dictionaries, tuples and sets of these basic data types. All other data can be stored in the returned dictionary, but will not be persisted

is_restart_file(file_name)

Is the given file an Ocellaris restart file

load_restart_file_functions(h5_file_name)

Load only the Functions stored on the given restart file Returns a dictionary of functions, does not affect the Simulation object itself (for switching meshes etc.)

load_restart_file_input(h5_file_name)

Load the input used in the given restart file

load_restart_file_results(h5_file_name)

Load the results stored on the given restart file

setup()
write_fields()

Write fields to file after end of time step

write_restart_file(h5_file_name=None)

Write a file that can be used to restart the simulation

class ocellaris.simulation.hooks.Hooks(simulation)

Bases: object

This class allows registering functions to run at given times during the simulation, e.g. to update some values for the next time step, report something after each time step or clean up after the simulation

add_custom_hook(hook_point, hook, description)

Add other type of hook, must give a string name for the hook name

add_matrix_ready_hook(hook, description)

Add a function that will run after matrix assembly

add_post_simulation_hook(hook, description)

Add a function that will run after the simulation is done

add_post_timestep_hook(hook, description, timer_name=None)

Add a function that will run after the solver in each time step

add_pre_simulation_hook(hook, description)

Add a function that will run before the simulation starts

add_pre_timestep_hook(hook, description, timer_name=None)

Add a function that will run before the solver in each time step

call_after(callable, description, *args, **kwargs)

Call this after the current hook calls are done

end_timestep()

Called by the solver at the end of a time step

Will run all post timestep hooks in the reverse order they have been added

matrix_ready(Aname, A, b=None)

Called by the solver after assembly and before a linear solve. Can be used i.e for studies of condition numbers and reporting matrix sizes etc

new_timestep(timestep_number, t, dt)

Called by the solver at the beginning of a new time step

Will run all pre timestep hooks in the reverse order they have been added

register_custom_hook_point(hook_point)

Add a new custom hook points to which hooks can be added

run_custom_hook(hook_point, *args, **kwargs)

Called by the solver at a custom point

Will run all custom hooks in the reverse order they have been added

show_hook_info()

Show all registered hooks

simulation_ended(success)

Called by the solver when the simulation is done

Will run all post simulation hooks in the reverse order they have been added

Parameters

  • success – True if nothing went wrong, False for

  • solution and other problems (diverging) –

simulation_started()

Called by the solver when the simulation starts

Will run all pre simulation hooks in the reverse order they have been added

class ocellaris.simulation.reporting.Reporting(simulation)

Bases: object

Central place to register reports that will be output during the simulation

get_report(report_name)

Get a the time series of a reported value

log_timestep_reports()

Write all reports for the finished time step to the log

report_timestep_value(report_name, value)

Add a timestep to a report

setup_report_plotting()

Setup the reports to be shown in plots during the simulation

class ocellaris.simulation.log.Log(simulation)

Bases: object

AVAILABLE_LOG_LEVELS = {'all': 10000000000.0, 'critical': LogLevel.CRITICAL, 'debug': LogLevel.DEBUG, 'error': LogLevel.ERROR, 'info': LogLevel.INFO, 'progress': LogLevel.PROGRESS, 'warning': LogLevel.WARNING}
debug(message='', flush=None)

Log a debug message

error(message, flush=None)

Log an error message

flush()

The simulation has started, flush to make sure input values are shown

or

The simulation is done. Make sure the output file is flushed, but keep it open in case some more output is coming

get_full_log()

Get the contents of all logged messages as a string

info(message='', flush=None)

Log an info message

set_log_level(log_level)

Set the Ocellaris log level (not the dolfin log level!)

setup()

Setup logging to file if requested in the simulation input

warning(message='', flush=None)

Log a warning message

write(message, msg_log_level=10000000000.0, color='%s', flush=None)

Write a message to the log without checking the log level