PS3D - 3D Pseudo-spectral code

PS3D was originally developed to solve the Euler equations for an incompressible inviscid flow in a horizontally- periodic domain and confined between parallel free-slip (including shear) surfaces. We especially targeted the solution of Beltrami flows. Since version 0.0.7, PS3D is also able to simulate buoyancy-driven turbulent flows.

1. Installation

1.1. Cloning the Repository

You can obtain the source code with

git clone https://github.com/matt-frey/ps3d.git

git clone git@github.com:matt-frey/ps3d.git

if you are a member of the project. We recommend users to run the latest release for production runs.

1.2. Prerequisites

We recommend to use the GNU Fortran compiler to build the executable. PS3D depends on MPI, HDF5 and NetCDF.

1.3. Configuring

Before you can compile, you must type

$ ./bootstrap

in the root directory of PS3D. Now, you are ready to configure PS3D

$ mkdir build
$ cd build
$ ../configure

We recommend to set the environment variables $MPI_DIR, $NETCDF_C_DIR and $NETCDF_FORTRAN_DIR to their root installation root directories. A list of configure options is given in Table 1.

Table 1. Important configuration options.
Option	Description
`--enable-verbose`	Compile in verbose mode to allow running with more output.
`--enable-buoyancy`	Enable buoyancy-driven flows.
`--enable-balance`	Enable balance mode (experimental).
`--enable-debug`	Compile in debug mode with backtrace, floating point operation checks etc.
`--enable-openmp`	Compile with shared memory parallelism
`--enable-iw-test-case`	Enable internal wave test case (available potential energy density)
`--enable-rt-test-case`	Enable Rayleigh-Taylor test case (available potential energy density)
`--prefix=$PREFIX`	Install directory when performing `make install`

1.4. Compiling

After Configuring PS3D you only need to type

$ make
$ make install

inside your build directory.

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

export PATH=$PREFIX/bin:$PATH

2. Conventions and Units

All computations in PS3D 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}$

3. Model

PS3D assumes an inviscid and incompressible fluid. The basic equations including buoyancy are given by

\[\begin{align} \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\,, \\ \label{eq:progb} & \frac{\mathrm{D} b}{\mathrm{D} t} = 0 \,. \end{align}\]

If the model is compiled without buoyancy, the buoyancy gradient term, i.e. $\boldsymbol{\nabla}b\times\hat{\boldsymbol{e}}_z$, is ignored.

4. Input

To run an PS3D 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

$ ps3d --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. PS3D input options and their default values.
Parameter	Default	Description
field_file	n/a	NetCDF input field file
field_step	-1 (last step)	Which step to read in the `field_file`.
stepper	'impl-diff-rk4'	Time integrator. Also `cn2`.
output%field_freq	1	Write after these many seconds to the field 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%write_field_stats	.true.	Enable / disable field statistics dump
output%field_list	n/a	Comma-separated list of gridded data to write (e.g. 'x_vorticity', 'buoyancy').
output%overwrite	.false.	Replace existing NetCDF files
output%basename	n/a	NetCDF output base name
filtering	'Hou & Li'	De-aliasing filter. Also, '2/3-rule'
vor_visc%nnu	n/a	If nnu = 1, this is molecular viscosity. If nnu > 1, this is hyperviscosity.
vor_visc%pretype	'roll-mean-max-strain'	Prefactor type to use: - vorch / bfmax: characteristic vorticity / buoyancy frequency - roll-mean-max-strain: rolling mean of gamma_max - roll-mean-bfmax: rolling mean of buoyancy frequency (bfmax) - constant: takes initial vorch or bfmax - us-max-strain: takes the maximum upper surface strain - max-strain: takes the maximum surface strain
vor_visc%roll_mean_win_size	1000	Window size for the rolling mean approach
time%limit	0.0	Time limit (s)
time%alpha	0.1	Scaling factor for the strain and buoyancy gradient time step
time%precise_stop	.false.	Stop exactly at the time limit

Note that there is also buoy_visc like vor_visc if buoyancy is enabled.

4.2. NetCDF Field File

The field file contains initial scalar fields and vector field components of a simulation. A list of supported fields is found in Table 4.

Table 4. Supported input fields.
Field name	Unit	Description
x_vorticity	1/s	Zonal vorticity component
y_vorticity	1/s	Meridional vorticity component
z_vorticity	1/s	Vertical vorticity component
buoyancy	m/s^2	Buoyancy field (if compiled with `--enable-buoyancy`)

4.3. How to run

In the directory examples you can find configuration scripts. You first need to generate a field input file by running the Beltrami program providing a *.nml file, e.g.

$ beltrami --config beltrami32x32x32.nml

This will generate a field file in NetCDF format. The name of the file is specified in the *.nml file which is beltrami_32x32x32.nc in this example. After that you run PS3D by

$ ps3d --config beltrami_32.config

The NetCDF file is specified in the configuration file too. In order to restart a simulation from a previous simulation, you need to update field_file and add the step number input with field_step to the configuration file. Please see the file beltrami_256_restart.config in the examples directory for an example.

5. Output

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

Table 5. List of PS3D output files.
Output file	Description
`<basename>_fields.nc`	NetCDF file containing gridded field output.
`<basename>_field_stats.nc`	NetCDF file containing diagnostics evaluated on the Eulerian grid.
`<basename>_alpha_time_step.asc`	ASCII file containing time step estimates for the maximum strain and maximum buoyancy gradient (if compiled with `--enable-verbose`)
`<basename>.csv`	ASCII file containing timings of the individual components of the code.

5.1. How to post-process

In the directory plotting we provide many pre-configured scripts to generate cross sections and 3D views of fields. The class nc_reader is used to retrieve data from the NetCDF file. The visualisation is done with matplotlib (version 3.5.2) and ParaView (version 5.10.1). You can install the Python environment with the provided requirements.txt file found in the root directory of this repository. The basic command to accomplish this is

$ conda create --name <env> --file requirements.txt

where <env> denotes a user-defined environment name like ps3d-env. To install conda, please read the relevant documentation.

The enstrophy production rates are calculated using the program production. Use the flag --help for further information. Note: The post-processing codes are currently switched off as we moved to distributed memory parallelism and these codes are not yet verified.

6. Citation

The source code can be cited using the latest Zenodo DOI. A corresponding paper is published and can be cited using the BibTeX below. You can also find further information at https://doi.org/10.1017/jfm.2022.1007.

@article{Dritschel_Frey_2023,
    title={The stability of inviscid {B}eltrami flow between parallel free-slip impermeable boundaries},
    volume={954},
    DOI={10.1017/jfm.2022.1007},
    journal={Journal of Fluid Mechanics},
    author={Dritschel, David and Frey, Matthias},
    year={2023},
    pages={A31}
}

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}\)