GitLocker: The Coding Marketplace

Description:

phantombuild 0.2.0

Phantom build

phantom-build: make building Phantom easier.

The main use case for phantom-build is to make it easy to generate reproducible Phantom builds for writing reproducible papers.

Table of contents

Install
Requirements
Usage

From the command line
Using Python

Details

A reproducible Phantom paper

Install
Install phantom-build with pip
pip install phantombuild

Requirements
Python 3.7+ with tomlkit, jinja, and click.
Usage
From the command line
You can use phantom-build at the command line.
python -m phantombuild setup config.toml

The command line program reads from a TOML config file, and uses the values
within to build Phantom and set up (possibly multiple) calculations. This is an
example config file with comments explaining the structure.
# This is a phantombuild config file
# It is a TOML file, see https://github.com/toml-lang/toml

# [phantom]
#
# The first section contains information required to build Phantom. You must
# provide:
#
# - path: the path to where the Phantom repository will live
# - setup: the Phantom SETUP Makefile variable
# - system: the Phantom SYSTEM Makefile variable
#
# You can optionally provide:
#
# - version: the Phantom version to use via a git commit hash
# - patches: a list of paths to patch files if you wish to modify Phantom
# - extra_options: a list of extra Phantom Makefile options
# - hdf5_path: the path to the HDF5 installation; this directory should have
# include and lib as sub-directories

[phantom]
path = "~/repos/phantom"
setup = "disc"
system = "ifort"
version = "d9a5507f"
patches = [
"phantom-d9a5507f-1.patch",
"phantom-d9a5507f-2.patch",
]
extra_options = ["MAXP=10000000", "ISOTHERMAL=no"]
hdf5_path = "/usr/local/opt/hdf5"

# [[runs]]
#
# The follow sections contain information for each run you wish to set up. You
# must provide:
#
# - prefix: the Phantom run prefix, e.g. files will be named prefix_00000.h5...
# - path: the path to the run directory
# - setup_file: the path to the phantomsetup .setup file
# - in_file: the path to the phantom .in file
#
# You can optionally provide:
#
# - job_script: the path to a Slurm job script if you wish to submit the run to
# a Slurm job scheduler

[[runs]]
prefix = "disc"
path = "~/runs/discs/disc_a"
setup_file = "~/repos/discs/disc_a.setup"
in_file = "~/repos/discs/disc_a.in"
job_script = "~/repos/discs/slurm.sh"

[[runs]]
prefix = "disc"
path = "~/runs/discs/disc_b"
setup_file = "~/repos/discs/disc_b.setup"
in_file = "~/repos/discs/disc_b.in"
job_script = "~/repos/discs/slurm.sh"

Using Python
You can use phantom-build with a Python script or from the Python REPL.
Import phantom-build.
import phantombuild

Choose Phantom build options. Only path, setup, and system are required arguments; the rest are optional.
# Options for Phantom build
phantom_path = '~/phantom'
version = '6666c55f'
patches = ['phantom-6666c55f.patch']
setup = 'disc'
system = 'gfortran'
extra_makefile_options = {'MAXP': '10000000', 'ISOTHERMAL': 'no'}
hdf5_path = '/usr/local/opt/hdf5'

Build Phantom.
# Build Phantom
phantombuild.build_phantom(
path=phantom_path,
version=version,
patches=patches,
setup=setup,
system=system,
hdf5_path=hdf5_path,
extra_options=extra_options,
)

Set options for Phantom calculation.
# Options for calculation
prefix = 'disc'
setup_file = '~/repos/paper/disc_a.setup'
in_file = '~/repos/paper/disc_a.in'
run_path = '~/runs/disc_a'
job_script = '~/repos/paper/slurm.sh'

Set up calculation, and (optionally) schedule job with Slurm.
# Set up calculation
phantombuild.setup_calculation(
prefix=prefix,
setup_file=setup_file,
in_file=in_file,
run_path=run_path,
phantom_path=phantom_path,
job_script=job_script,
)

Details
The phantom-build functions build_phantom and setup_calculation rely on the following functions:

Use get_phantom to clone Phantom from the GitHub repository, or to check if already cloned.
Use checkout_phantom_version to check out a particular Phantom version based on a git commit hash.
Use patch_phantom to apply patches.
Use schedule_job to schedule a calculation with a job scheduler, e.g. Slurm.

A reproducible Phantom paper
Say you want to have a reproducible Phantom build for a paper. You want to work from a particular version of Phantom, and you need to apply patches to that version.

First, clone Phantom.
# Clone Phantom
phantom_path = '~/phantom'
phantombuild.get_phantom(path=phantom_path)

Now, check out a particular version of Phantom based on the git commit hash.
# Checkout particular commit
version = '6666c55f'
phantombuild.checkout_phantom_version(path=phantom_path, version=version)

Then, apply your patch.
# Apply patch
patch = 'phantom-6666c55f.patch'
phantombuild.patch_phantom(path=phantom_path, patch=patch)

Now, build Phantom with particular Makefile options.
# Makefile options
setup = 'disc'
system = 'gfortran'
extra_makefile_options = {'MAXP': '10000000'}
hdf5_path = '/usr/local/opt/hdf5'

# Compile Phantom
phantombuild.build_phantom(
path=phantom_path,
setup=setup,
system=system,
hdf5_path=hdf5_path,
extra_options=extra_options,
)

Set up your calculation with phantomsetup.
# Options for particular calculation
prefix = 'disc'
setup_file = '~/repos/paper/disc_a.setup'
in_file = '~/repos/paper/disc_a.in'
run_path = '~/runs/disc_a'

# Set up calculation
phantombuild.setup_calculation(
prefix=prefix,
setup_file=setup_file,
in_file=in_file,
run_path=run_path,
phantom_path=phantom_path,
)

Schedule your job with Slurm.
job_file = '~/repos/paper/slurm.sh'
phantombuild.schedule_job(run_path=run_path, job_file=job_file)

You can write the above into a script included with the git repository of the paper to help make your paper reproducible. Of course, you also need to include all the Phantom .in and .setup files. For managing those files, see phantom-config. For setting up Phantom simulations in pure Python (no Fortran required), see (the work in progress) phantom-setup.