Package: phantombuild
Phantom buildphantom-build: make building Phantom easier.The main use case for phantom-build is to make it easy to generate reproduciblePhantombuilds for writing reproducible papers.Table of contentsInstallRequirementsUsageFrom the command lineUsing PythonDetailsA reproducible Phantom paperInstallInstall phantom-build with pippipinstallphantombuildRequirementsPython 3.7+ withtomlkit,jinja, andclick.UsageFrom the command lineYou can use phantom-build at the command line.python-mphantombuildsetupconfig.tomlThe 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 PythonYou can use phantom-build with a Python script or from the Python REPL.Import phantom-build.importphantombuildChoose Phantom build options. Onlypath,setup, andsystemare required arguments; the rest are optional.# Options for Phantom buildphantom_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 Phantomphantombuild.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 calculationprefix='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 calculationphantombuild.setup_calculation(prefix=prefix,setup_file=setup_file,in_file=in_file,run_path=run_path,phantom_path=phantom_path,job_script=job_script,)DetailsThe phantom-build functionsbuild_phantomandsetup_calculationrely on the following functions:Useget_phantomto clone Phantom from theGitHub repository, or to check if already cloned.Usecheckout_phantom_versionto check out a particular Phantom version based on a git commit hash.Usepatch_phantomto apply patches.Useschedule_jobto schedule a calculation with a job scheduler, e.g. Slurm.A reproducible Phantom paperSay 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 Phantomphantom_path='~/phantom'phantombuild.get_phantom(path=phantom_path)Now, check out a particular version of Phantom based on the git commit hash.# Checkout particular commitversion='6666c55f'phantombuild.checkout_phantom_version(path=phantom_path,version=version)Then, apply your patch.# Apply patchpatch='phantom-6666c55f.patch'phantombuild.patch_phantom(path=phantom_path,patch=patch)Now, build Phantom with particular Makefile options.# Makefile optionssetup='disc'system='gfortran'extra_makefile_options={'MAXP':'10000000'}hdf5_path='/usr/local/opt/hdf5'# Compile Phantomphantombuild.build_phantom(path=phantom_path,setup=setup,system=system,hdf5_path=hdf5_path,extra_options=extra_options,)Set up your calculation withphantomsetup.# Options for particular calculationprefix='disc'setup_file='~/repos/paper/disc_a.setup'in_file='~/repos/paper/disc_a.in'run_path='~/runs/disc_a'# Set up calculationphantombuild.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.inand.setupfiles. For managing those files, seephantom-config. For setting up Phantom simulations in pure Python (no Fortran required), see (the work in progress)phantom-setup.