EPIC - Elliptical Parcel-In-Cell

The EPIC framework is an open-source project developed to simulate fluid flows where the Lagrangian parcels are described by ellipses in 2D and ellipsoids in 3D. Although EPIC targets the simulation of cloud and atmospheric systems, the core idea of advecting elliptical parcels is applicable to any fluid dynamical system.

1. Installation

Note that any occurrences of $PREFIX in the following subsections denote the installation directory of EPIC.

1.1. Cloning the Repository

Users can obtain the source code by

git clone https://github.com/EPIC-model/epic.git

It is however recommended to use the latest release for production runs. EPIC contributors can also clone the repository using the SSH version

git clone git@github.com:EPIC-model/epic.git

1.2. Prerequisites

EPIC is implemented in Fortran; hence, a Fortran compiler is required. We recommend to use GNU Fortran compiler. Also, the 3D model uses MPI to run on distributed memory architectures. It further depends on HDF5 and NetCDF. Scripts to install HDF5 and NetCDF are found in the source code subdirectory dependencies. No guarantee can be given for a successful installation with these scripts. Optionally, users can install Python in order to use the provided pre- and post-processing scripts. It is generally recommended to create a separate Python virtual environment using conda. After installing conda, all necessary Python packages for EPIC can be installed via

$ conda config --add channels conda-forge
$ conda create --name <env> python=3.12.0 --file requirements.txt

where <env> is the name of the environment. The file requirements.txt is contained in the root directory of EPIC.

Note: In order to install the Python scripts you need to configure EPIC with --enable-python.

1.3. Configuring

Assuming you are in the root directory of EPIC, you must first create the configure script and all Makefiles by calling

$ ./bootstrap

in your terminal. You then create a build directory and configure EPIC

$ mkdir build
$ cd build
$ ../configure

Note that the environment variables $MPI_DIR, $NETCDF_C_DIR and $NETCDF_FORTRAN_DIR must be set to the proper installation root directories. The most important configure options are given in Table 1. You can also append the flag --help to see all available options.

Table 1. Important configuration options.
Option	Description
`--enable-3d`	Compile EPIC 3D alongside EPIC 2D
`--enable-debug`	Compile in debug mode with backtrace, floating point operation checks etc.
`--enable-diagnose`	Enables more diagnostics and output (only in EPIC 2D)
`--enable-dry-mode`	Install dry model, that is no moist physics model
`--enable-openmp`	Compile with shared memory parallelism
`--enable-python`	Install Python pre- and pos-processing scripts
`--enable-scalasca`	Compile EPIC with performance analysis (this extremely slows down EPIC)
`--enable-unit-tests`	Compile unit tests
`--enable-verbose`	Compile in verbose mode to allow running with more output
`--prefix=$PREFIX`	Install directory when performing `make install`

1.4. Compiling

After Configuring EPIC you only need to type

$ make
$ make install

inside your build directory.

Note: You can add the bin directory $PREFIX/bin to your $PATH and PYTHONPATH environment variables with

export PATH=$PREFIX/bin:$PATH
export PYTHONPATH=$PREFIX/bin:$PYTHONPATH

2. Conventions and Units

All computations in EPIC are performed in SI units. The position is defined in Cartesian coordinates $\boldsymbol{x}=(x, y, z)$, where $x$ is the zonal, $y$ the meridional and $z$ the vertical direction. A list of the units of the prognostic variables is provided in Table 2.

Table 2. List of units of prognostic variables.
Prognostic variable	Symbol	Unit
Zonal vorticity	$\xi$	$s^{-1}$
Meridional vorticity	$\eta$	$s^{-1}$
Vertical vorticity	$\zeta$	$s^{-1}$
Zonal velocity	$u$	$ms^{-1}$
Meridional velocity	$v$	$ms^{-1}$
Vertical velocity	$w$	$ms^{-1}$
Buoyancy	$b$	$m s^{-2}$
Humidity	$q$	$-$

3. Model

EPIC simulates buoyancy-driven flows using the Boussinesq approximation and assuming an inviscid and incompressible fluid. The basic equations are given by

\[\begin{align} \label{eq:progu} & \frac{\mathrm{D}\boldsymbol{u}}{\mathrm{D} t}+2\Omega\,\hat{\boldsymbol{e}}_z\times\boldsymbol{u} = -\frac{\nabla p}{\rho_0}+b\,\hat{\boldsymbol{e}}_z \,, \\ \label{eq:progb} & \frac{\mathrm{D} b_l}{\mathrm{D} t} = 0 \,, \\ \label{eq:progq} & \frac{\mathrm{D} q}{\mathrm{D} t} = 0 \,. \end{align}\]

By evolving the vorticity $\boldsymbol{\omega} = \boldsymbol{\nabla}\times\boldsymbol{u}$, the pressure term in the momentum equation vanishes

\[\begin{equation} \label{eq:progo} \frac{\mathrm{D}\boldsymbol{\omega}}{\mathrm{D} t} = (2\Omega+ \boldsymbol{\omega})\boldsymbol{\cdot}\boldsymbol{\nabla}\boldsymbol{u} + \boldsymbol{\nabla}b\times\hat{\boldsymbol{e}}_z\,. \end{equation}\]

4. Input

To run an EPIC simulation users must provide a Configuration file and a field file in NetCDF format. The latter is listed inside the configuration file under the option field_file. You then simply type

$ epic2d --config input.config
$ epic3d --config input.config

in the terminal to start a simulation.

4.1. Configuration File

A configuration file contains user-defined rutime options. Almost all parameters have default values that may be adapted to the number of spatial dimensions. The list of options and their recommended values are given in Table 3.

Table 3. EPIC input options and their default values.
Parameter	Default	Description
field_file	n/a	NetCDF input field file
field_tol	1.0d-10	Tolerance for parcel generation from field file
flux_file	n/a	Buoyancy flux file for convective boundary layer
rk_order	4	Low-storage Runge-Kutta order (3 and 4 supported)
output%field_freq	1	Write after these many seconds to the field NetCDF file
output%parcel_freq	1	Write after these many seconds to the parcel NetCDF file
output%parcel_stats_freq	1	Write after these many seconds to parcel stats NetCDF file
output%field_stats_freq	1	Write after these many seconds to the field stats NetCDF file
output%write_fields	.true.	Enable / disable field dump
output%field_list	n/a	Comma-separated list of gridded data to write (3D only) (e.g. 'x_vorticity', 'buoyancy'). Default: vorticity components, velocity components, buoyancy, humidity, gridded volume
output%write_parcels	.true.	Enable / disable parcel dump
output%parcel_list	n/a	Comma-separated list of parcel attributes to write (3D only). Default: vorticity components, position, buoyancy, shape matrix components, volume, humidity
output%write_parcel_stats	.true.	Enable / disable parcel statistics
output%write_field_stats	.true.	Enable / disable field statistics
output%overwrite	.false.	Replace existing NetCDF files
output%basename	n/a	NetCDF output base name
parcel%size_factor	1	Factor to increase max. number of parcels
parcel%grow_factor	1.2	Factor to increase the parcel container size in the parcel splitting routine
parcel%shrink_factor	0.8	Factor to reduce the parcel container size
parcel%n_per_cell	9 (2D) or 8 (3D)	Initial number of parcels per cell
parcel%lambda_max	4	Maximum parcel aspect ratio
parcel%min_vratio	40 (2D) or 20 (3D)	Minimum ratio of grid cell volume / parcel volume
parcel%max_vratio	2.89	Maximum ratio of grid cell area / parcel area (2D only)
parcel%correction_iters	2	How many parcel correction iterations
parcel%gradient_pref	1.8	Gradient correction prefactor
parcel%max_compression	0.5	Gradient correction maximum compression
time%limit	0.0	Time limit (s)
time%alpha	0.2	Scaling factor for the strain and buoyancy gradient time step
time%precise_stop	.false.	Stop exactly at the time limit

4.2. NetCDF Field File

The field file contains initial scalar fields and vector field components of a simulation. A list of supported fields in 2D and 3D is found in Table 4. You can either write your own tool to generate such files or use our provided Python scripts. Below you can find an example where the vorticity field of a Taylor-Green flow in 2D is initialised and written to a file.

Table 4. Supported input fields.
Field name	Unit	Description
x_vorticity	1/s	Zonal vorticity component (3D only)
y_vorticity	1/s	Meridional vorticity component (3D only)
z_vorticity	1/s	Vertical vorticity component (field name in 2D: vorticity)
buoyancy	m/s^2	Buoyancy field
humidity	-	Humidity field (3D only)

Example of writing a field file that can be parsed by EPIC.

#!/usr/bin/env python
from tools.nc_fields import nc_fields
import numpy as np

try:
    ncf = nc_fields()

    ncf.open('taylor_green.nc')

    # velocity field:
    # u(x, z) = A * cos(ax + d) * sin(bz + e)
    # w(x, z) = B * sin(ax + d) * cos(bz + e)

    # vorticity:
    # zeta = (B * a - A * b) * cos(ax + d) * cos(bz + e)

    # amplitudes
    A = 0.5
    B = -1.0

    # frequencies
    a = 2.0
    b = 1.0

    # phases
    d = 0.5 * np.pi
    e = 0.0

    # number of cells
    nx = 32
    nz = 32

    # domain origin
    origin = (-0.5 * np.pi, -0.5 * np.pi)

    # domain extent
    extent = (np.pi, np.pi)

    # mesh spacings
    dx = extent[0] / nx
    dz = extent[1] / nz

    vorticity = np.zeros((nz+1, nx))

    # ranges from 0 to nx-1
    for i in range(nx):
        # ranges from 0 to nz
        for j in range(nz+1):
            x = origin[0] + i * dx
            z = origin[1] + j * dz
            vorticity[j, i] = (B * a - A * b) * np.cos(a * x + d) * np.cos(b * z + e)

    # write all provided fields
    ncf.add_field('vorticity', vorticity, unit='1/s')

    ncf.add_box(origin, extent, [nx, nz])

    ncf.close()

except Exception as err:
    print(err)

4.3. NetCDF Parcel File

Instead of gridded fields, a simulation can also be started with a parcel distribution. A parcel NetCDF file must contain the parcel shape components, their volume and position as well as either the vorticity components or buoyancy. In non-dry mode, parcels further carry humidity. As for the gridded fields, we provide Python tools to write such NetCDF files. Note that EPIC can only be started with parcels via the restart interface (see Restarting).

Example of writing a parcel file that can be parsed by EPIC.

#!/usr/bin/env python
from tools.nc_parcels import nc_parcels

try:

    # domain
    origin = ...
    extent = ...
    ncells = ...


    ncp = nc_parcels()

    ncp.open('example_parcels.nc')

    ncp.add_box(origin, textent, ncells)

    # initialise parcel attributes with some meaningful input
    ...

    # write parcel attributes
    ncp.add_dataset('x_position', position[:, 0], unit='m')
    ncp.add_dataset('y_position', position[:, 1], unit='m')
    ncp.add_dataset('z_position', position[:, 2], unit='m')

    ncp.add_dataset('buoyancy', buoyancy, unit='m/s^2')

    ncp.add_dataset('humidity', humidity, unit='1')

    ncp.add_dataset('volume', volume, unit='m^3')

    ncp.add_dataset('x_vorticity', vorticity[:, 0], unit='1/s')
    ncp.add_dataset('y_vorticity', vorticity[:, 1], unit='1/s')
    ncp.add_dataset('z_vorticity', vorticity[:, 2], unit='1/s')

    ncp.add_dataset('B11', B[:, 0], unit='m^2')
    ncp.add_dataset('B12', B[:, 1], unit='m^2')
    ncp.add_dataset('B13', B[:, 2], unit='m^2')
    ncp.add_dataset('B22', B[:, 3], unit='m^2')
    ncp.add_dataset('B23', B[:, 4], unit='m^2')

    ncp.close()

except Exception as ex:
    print(ex)

4.4. Restarting

In order to restart EPIC use the restart option as follows

$ epic2d --config input.config --restart input.nc
$ epic3d --config input.config --restart input.nc

where input.nc is either a gridded field or parcel file. If the field file contains multiple time steps, the last step is taken.

5. Output

EPIC writes the following files, where <basename> is to be replaced by the character string that is passed to EPIC via the argument output%basename in the configuration file:

Table 5. List of EPIC output files.
Output file	Description
`<basename>_xxxxxxxxxx_parcels.nc`	NetCDF containing parcel output where `xxxxxxxxxx` is replaced with the file number, e.g. `moist_0000000002_parcels.nc`.
`<basename>_fields.nc`	NetCDF file containing gridded field output.
`<basename>_field_stats.nc`	NetCDF file containing diagnostics evaluated on the Eulerian grid.
`<basename>_parcel_stats.nc`	NetCDF file containing diagnostics evaluated using the Lagrangian parcels.
`<basename>_alpha_time_step.asc`	ASCII file containing time step estimates for the maximum strain and maximum buoyancy gradient.
`<basename>.csv`	ASCII file containing timings of the individual components of the code.

Note	The frequency of writing to the respective netCDF files is controlled via the construct `output` in the configuration file.

Tip	The command `ncdump` is useful to inspect a netCDF file, i.e. `ncdump filename.nc \| less` where `filename.nc` is a netCDF file.

6. Citation

Please cite the two-dimensional EPIC model with

@article{Frey2022,
    title = {{EPIC}: The {E}lliptical {P}arcel-{I}n-{C}ell method},
    journal = {Journal of Computational Physics: X},
    volume = {14},
    pages = {100109},
    year = {2022},
    issn = {2590-0552},
    doi = {https://doi.org/10.1016/j.jcpx.2022.100109},
    url = {https://www.sciencedirect.com/science/article/pii/S2590055222000051},
    author = {Matthias Frey and David Dritschel and Steven B\"oing}
}

The reference for the three-dimensional EPIC model is

@article{FREY2023100136,
    title = {The {3D} {E}lliptical {P}arcel-{I}n-{C}ell ({EPIC}) method},
    journal = {Journal of Computational Physics: X},
    volume = {17},
    pages = {100136},
    year = {2023},
    issn = {2590-0552},
    doi = {https://doi.org/10.1016/j.jcpx.2023.100136},
    url = {https://www.sciencedirect.com/science/article/pii/S2590055223000148},
    author = {Matthias Frey and David Dritschel and Steven B\"oing}
}

Prognostic variable	Symbol	Unit
Zonal vorticity	\(\xi\)	\(s^{-1}\)
Meridional vorticity	\(\eta\)	\(s^{-1}\)
Vertical vorticity	\(\zeta\)	\(s^{-1}\)
Zonal velocity	\(u\)	\(ms^{-1}\)
Meridional velocity	\(v\)	\(ms^{-1}\)
Vertical velocity	\(w\)	\(ms^{-1}\)
Buoyancy	\(b\)	\(m s^{-2}\)
Humidity	\(q\)	\(-\)