Skip to main content

phantom-build is designed to make building Phantom easier

Project description

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.

Build Status Coverage Status PyPI

Table of contents

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.

  1. First, clone Phantom.

    # Clone Phantom
    phantom_path = '~/phantom'
    phantombuild.get_phantom(path=phantom_path)
    
  2. 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)
    
  3. Then, apply your patch.

    # Apply patch
    patch = 'phantom-6666c55f.patch'
    phantombuild.patch_phantom(path=phantom_path, patch=patch)
    
  4. 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,
    )
    
  5. 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,
    )
    
  6. 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

phantombuild-0.2.0.tar.gz (11.1 kB view details)

Uploaded Source

Built Distribution

phantombuild-0.2.0-py3-none-any.whl (10.5 kB view details)

Uploaded Python 3

File details

Details for the file phantombuild-0.2.0.tar.gz.

File metadata

  • Download URL: phantombuild-0.2.0.tar.gz
  • Upload date:
  • Size: 11.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.1.3.post20200325 requests-toolbelt/0.9.1 tqdm/4.44.1 CPython/3.7.6

File hashes

Hashes for phantombuild-0.2.0.tar.gz
Algorithm Hash digest
SHA256 5099fd78b48c788371d09f8f2053cbf81d374401e49f786f4a01fff210404ebd
MD5 f8689491e2671ec37ae0191470f1db88
BLAKE2b-256 a87d2496ed6978aa9e23249d6af18a6995787e1f4221924e6316c5b696e45a88

See more details on using hashes here.

File details

Details for the file phantombuild-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: phantombuild-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 10.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.1.3.post20200325 requests-toolbelt/0.9.1 tqdm/4.44.1 CPython/3.7.6

File hashes

Hashes for phantombuild-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 6fb39c4626b34204bd579051f027fe266165ee8230f08a6e273be8e0786c86eb
MD5 ec27486254da86b8a5acaddef32b4c9a
BLAKE2b-256 e946ef975d8891e2e39d4264ca75757f4306d8aa2221db5789c99625b8cc9e88

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page