Details

This section lists all options and its related dependencies.

Options (=Default Value)

The options are mutually independent to each other.

-DSERIAL_MODE (=OFF)

	Notes	Dependency	Python dependency
Parallel Mode (OFF)	Compile libyt using MPI.	MPI_PATH	mpi4py
Serial Mode (ON)	Compile libyt using GCC.

Make sure Python bindings for MPI (mpi4py), MPI used for compiling simulation and libyt are the same. Check how to install mpi4py here.

-DINTERACTIVE_MODE (=OFF)

	Notes	Dependency
Normal Mode (OFF)	Shut down and terminate all the processes including simulation, if error occurs during in situ analysis.
Interactive Mode (ON)	Will not terminate the processes if error occurs while doing in situ analysis. Support Interactive Python Prompt and Reloading Script.	READLINE_PATH

-DJUPYTER_KERNEL (=OFF)

	Notes	Dependency	Python dependency
Jupyter Kernel Mode (ON)	Activate Jupyter kernel and enable JupyterLab UI. (See Jupyter Notebook Access)	nlohmann_json_DIR cppzmq_DIR xtl_DIR xeus_DIR xeus-zmq_DIR ZeroMQ_DIR	jupyter_libyt jupyter-client jedi(Optional)

-DSUPPORT_TIMER (=OFF)

	Notes
Time Profiling (ON)	Support time profiling. (See Time Profiling)

Dependencies

• Option indicates under what circumstances will we need this dependency.

• Get by libyt indicates whether libyt will fetch and build the dependency itself, if the paths aren’t provided. The downloaded content will be stored under libyt/vendor, and libyt will link to dependencies inside this folder.

Dependency path	Required version	Notes	Option	Get by libyt
PYTHON_PATH	>=3.7	Python installation prefix, the path contains folders include, lib etc. The Python environemnt will be used in in situ analysis.	Always	No
MPI_PATH		MPI installation prefix. The path contains folders include and lib. Make sure you are using the same MPI to compile libyt and your simulation code.	-DSERIAL_MODE=OFF	No
READLINE_PATH		GNU readline library installation prefix. The path contains folders include and lib. Generally, this library exists in Linux and macOS, we don’t need to explicitly provide the path.	-DINTERACTIVE_MODE=ON	No
nlohmann_json_DIR	>=3.2.0, <4.0.0	Path to nlohmann_jsonConfig.cmake after installing nlohmann_json.	-DJUPYTER_KERNEL=ON	Yes
xtl_DIR	>=0.7.0, <0.8.0	Path to xtlConfig.cmake after installing xtl.	-DJUPYTER_KERNEL=ON	Yes
ZeroMQ_DIR	>=4.2.5, <5.0.0	Path to ZeroMQConfig.cmake after installing ZeroMQ. (Some system may already have ZeroMQ installed.)	-DJUPYTER_KERNEL=ON	Yes
cppzmq_DIR	>=4.8.1, <5.0.0	Path to cppzmqConfig.cmake after installing cppzmq.	-DJUPYTER_KERNEL=ON	Yes
xeus_DIR	>=3.0.0, <4.0.0	Path to xeusConfig.cmake after installing xeus.	-DJUPYTER_KERNEL=ON	Yes
xeus-zmq_DIR	1.x release	Path to xeus-zmqConfig.cmake after installing xeus-zmq.	-DJUPYTER_KERNEL=ON	Yes

If our system doesn’t have readline installed, use system package manager (ex: brew, apt) to install. If we want to compile and install from the source code ourselves, make sure --with-curses is used when configuring.

Python Dependencies

• Option indicates under what circumstances will we need this package.

Python package	pip	Required version	Notes	Option
NumPy	numpy	<2.0	The fundamental package for scientific computing with Python.	Always
yt	yt		The core analytic tool.	Always
yt_libyt	yt-libyt		yt frontend for libyt.	Always
mpi4py	mpi4py		Python bindings for the Message Passing Interface (MPI) standard. Make sure mpi4py used in Python and MPI used in simulation are matched. (Check how to install mpi4py here.)	-DSERIAL_MODE=OFF
jedi	jedi		Support auto-completion in Jupyter Notebook and JupyterLab. (We will have this if IPython is already installed.)	-DJUPYTER_KERNEL=ON
jupyter-client	jupyter-client	>=8.0.0	Jupyter Client.	-DJUPYTER_KERNEL=ON
jupyter_libyt	jupyter-libyt		Jupyter kernel provisioner for libyt.	-DJUPYTER_KERNEL=ON

Note

jupyter-client and jupyter_libyt are used for launching Jupyter Notebook and JupyterLab. Make sure the Python environment used for launching the notebook have them installed.

The Python used in in situ analysis which is also for compiling libyt and the Python used for launching Jupyter Notebook/JupyterLab might be different. For example, when running libyt in HPC cluster, the Python environment is different from the one starting Jupyter Notebook on your local laptop. (See Jupyter Notebook Access)

Step-by-Step Instructions

1. Toggle options, set paths and generate files to build the project. This can be done through either (a) or (b):

   (a) Set it through editing CMakeLists.txt at root directory. For example, this uses option -DSERIAL_MODE=OFF and provides MPI_PATH:

   option(SERIAL_MODE "Compile library for serial process" OFF)
   set(MPI_PATH "<path-to-mpi-prefix>" CACHE PATH "Path to MPI installation prefix (-DSERIAL_MODE=OFF)")
   

   (b) Set the options and paths through command line. For example, the flags here are equivalent to the above:

   -DSERIAL_MODE=OFF -DMPI_PATH=<path-to-mpi-prefix>
   

2. [Optional] Set the GCC compiler, export the environment variable CC to target gcc compiler and CXX to target g++ compiler before running cmake. For example:

   export CC=/software/gcc/bin/gcc
   export CXX=/software/gcc/bin/g++
   

   It should support c++14.

3. Generate files for project, <1-(b)> contains the flags in step 1-(b):

   cd libyt # go to the root of the project
   cmake -B <build-dir-name> -S . <1-(b)>
   

4. Build the project:

   cmake --build <build-dir-name>
   

5. Install the library:

   cmake --install <build-dir-name> --prefix <libyt-install-prefix> 
   

Examples

• The following builds libyt in serial mode using user designated GCC compiler and then installs the library in /home/user/softwares/libyt:

  cd libyt                                                     # go to project root directory
  export CC=/software/gcc/8.4.0/bin/gcc                        # set gcc compiler
  export CXX=/software/gcc/8.4.0/bin/g++                       # set g++ compiler
  rm -rf build                                                 # clean up previous build
  cmake -B build -S . -DSERIAL_MODE=ON                         # generate files for project
  cmake --build build                                          # build the project
  cmake --install build --prefix /home/user/softwares/libyt    # install
  

• The following builds libyt in parallel mode using user designated MPI compiler and then installs the library in /home/user/softwares/libyt:

  cd libyt                                                                       # go to project root directory
  rm -rf build                                                                   # clean up previous build
  cmake -B build -S . -DSERIAL_MODE=OFF -DMPI_PATH=/software/openmpi/4.1.1-gnu   # set mpi path and generate files for project
  cmake --build build                                                            # build the project
  cmake --install build --prefix /home/user/softwares/libyt                      # install