Skip to content

Latest commit

 

History

History
177 lines (139 loc) · 7.79 KB

GETTING_STARTED.md

File metadata and controls

177 lines (139 loc) · 7.79 KB
Raw

Getting started

This is a general guide for those who have a basic familiarity with GNU/Linux operating systems.

Windows users: follow the guide to set up the Windows Subsystem for Linux. This will allow you run a linux system with (close to) native performance provided you use WSL2 (generally the default for new installations unless you have hardware virtualization disabled in your motherboard UEFI).

Install the dependencies

To install the dependencies on ubuntu

sudo apt install bear build-essential liblapack-dev libopenmpi-dev libreadline-dev libboost-dev

Windows users: add python3 to that list, as it doesn't come installed by default on WSL.

Similarly for archlinux:

sudo pacman -Syu base-devel git lapack openmpi readline boost

Eilmer gas dynamics (UQ Gas Dynamics Toolkit)

If you with to use the GDTk chemistry models, then you will need a D compiler package.

sudo apt install ldc

Archlinux

sudo pacman -S ldc

Compiling the code

Follow these instructions to download and build a copy of the code. If you have any problems or weird error messages, then ask a question. Communication through the discussion board for most issues is preferable, so that anyone running into the same problem can be informed.

Getting a copy of Cerberus

NOTE: Do not use the "Download Zip" option in github.

Clone Cerberus and cd into the directory:

git clone https://github.com/plasmasimuq/cerberus && cd cerberus

If you have an ssh key set up for github

git clone git@github.com:plasmasimuq/cerberus && cd cerberus

Building

For most simulation use cases, you shouldn't need to change any build options. If you intend to use some of the more experimental options, or the external UQ Gas Dynamics Toolkit, then copy Make.local.template as Make.local in the root directory:

cp Make.local.template Make.local

Edit Make.local, the build system will include it when you run make.

To build, run the following command in the cerberus root directory:

make cerberus -j$(nproc)

Alternatively, you can specify build flags in the command line,

make cerberus USE_EB=FALSE AMREX_PARTICLES=FALSE -j$(nproc)

Look inside Make.local.template for descriptions of the build flags. Commented values are the defaults unless noted otherwise.

NOTE: the -j option specifies the number of threads for parallel compilation and should be set to an appropriate value. In this case, we set it to the output of the nproc command.

Once the build process has completed, you can run the executable MFP.2d.STUFF.ex directly from the build directory.

UQ Gas Dynamics Toolkit (Eilmer)

To expand the capabilities of the code it is possible to use the Eilmer gas models implemented in the UQ Gas Dynamics Toolkit. This requires the download, compilation, and installation of the Eilmer gas library (found at src/gas in the Eilmer source) as well as the D-language compiler and runtime (see instructions here). GDTk will be installed to EILMER_HOME automatically when calling the make command with EILMER_GAS=TRUE if EILMER_INSTALL_LIB=TRUE. Alternatively, just set EILMER_HOME if you already have GDTk installed on your system.

When building with the GDTk modules enabled, ensure that the *.so files from the $(EILMER_HOME)/lib/ are in one of the following locations:

  1. (Default) In $(EILMER_HOME)/lib where $(EILMER_HOME) is defined in the Makefile, by default it is cerberus/gdtkinst.
cerberus/
├─ MFP.STUFF.ex
├─ gdtkinst/
│  ├─ *.so
  1. The same directory as the MFP executable:
cerberus/
├─ MFP.STUFF.ex
├─ *.so
  1. In a directory called lib within the same directory as the MFP executable:
cerberus/
├─ MFP.STUFF.ex
├─ lib/
│  ├─ *.so

Running simulations

Once the build process has completed, if you're using the GDTk gas models, then run:

source env

from the root of the repository.

See Exec/testing/ for example simulations. We are still working on the documentation for these and the run scripts may not always work.

The executable can be run in parallel using mpirun and expects an inputs file that defines the simulation. This inputs file is made up of two parts; a section using the AMReX style configuration which defines the simulation infrastructure, and a Lua script which defines the physics side of the simulation including initial conditions and physical reference parameters.

To run a simulation simply call the executable along with an inputs file. For example, using the Isotope-RMI test case:

cd Exec/testing/Wedge
mpirun ../../../MFP.2d.gnu.MPI.EB.PARTICLES.ex Wedge.inputs

All output files will be saved to the location where the run command was issued.

The accompanying run scripts may be used to automatically launch the test cases, but they are not guaranteed to be up-to-date.

Visualisation

Visualisation can be carried out using VisIt or by using the provided python scripts in vis.

To use visit, generate movie.visit after running the simulation. Carrying on from our wedge example:

../visit.sh .
visit -o movie.visit

This is assuming that you have VisIt installed and available in your PATH.

Using the gas and reaction models

An example is provided in tests/Eilmer-Gas. This example shows how to prepare the files required by Eilmer using the prep-gas and prep-chem routines that are bundled in the Eilmer install. The gas model specified for a state must be of type eilmer and specify the name of the file that defines the gas model as generated by prep-gas. To define species within a state, the names and charges of each must be specified along with the mass fraction alpha.

The specific heats and masses of the species are calculated from the gas model (make sure to define appropriate reference quantities).

Only n-1 alpha values need to be defined, for n species, as the n-th value is calculated by assuming that all alpha values sum to unity. The reactions scheme is defined as an action, where the species named within the reactions scheme are assumed to be held by the associated states. Species can be defined across multiple states.

Advanced: Python debugging

It is possible to visualise the raw data while a simulation is running for debugging purposes. You will require the python library headers as well as numpy (with headers) and matplotlib

Updating Cerberus and submodules

Update cerberus with git pull. This should automatically update submodules to the latest compatible version as well.

To manually update submodules,

git submodule update --init --recursive

Documentation

We are still working on documenting this code. For now, see the notes in (doc/)[doc], and rely on the test inputs files to learn how to run simulations.

If you have worked with the code, please consider adding some notes to the wiki (we are happy to grant write access)

Developing

Pull requests are welcome. If you intend to make additions to the code and don't have a C++ development environment set up, we provide recommended extensions for the Visual Studio Code editor. When you open this repository in vscode, it will ask if you want to install the recommended extensions. Use the development build command to get full autocomplete, jump to reference/definition, etc.

We welcome all pull requests submissions.