pyAMReX is part of AMReX.
Due to its highly experimental nature, we develop it currently in a separate respository.
We will add further information here once first development versions are ready for testing.
to do
- pip/pypa
- conda-forge
- spack
- brew
- ...
to do
import pyamrex
small_end = pyamrex.Int_Vect()
big_end = pyamrex.Int_Vect(2, 3, 4)
b = pyamrex.Box(small_end, big_end)
print(b)
# ...
If you are new to CMake, this short tutorial from the HEP Software foundation is the perfect place to get started with it.
If you just want to use CMake to build the project, jump into sections 1. Introduction, 2. Building with CMake and 9. Finding Packages.
pyAMReX depends on the following popular third party software.
- a mature C++14 compiler: e.g. g++ 5.0+, clang 5.0+, VS 2017+
- CMake 3.18.0+
- AMReX development: we automatically download and compile a copy of AMReX
- pybind11 2.6.2+: we automatically download and compile a copy of pybind11 (new BSD)
Optional dependencies include:
- mpi4py 2.1+: for multi-node and/or multi-GPU execution
- CCache: to speed up rebuilds (needs 3.7.9+ for CUDA)
- further optional dependencies of AMReX
macOS/Linux:
spack env activate -d .
# optional:
# spack add cuda
spack install
(in new terminals, re-activate the environment with spack env activate -d .
again)
or macOS/Linux:
brew update
brew install ccache cmake libomp mpi4py numpy open-mpi python
Now, cmake --version
should be at version 3.18.0 or newer.
Or go:
# optional: --user
python3 -m pip install -U pip setuptools wheel
python3 -m pip install -U cmake
For example, using the Clang compiler:
export CC=$(which clang)
export CXX=$(which clang++)
If you also want to select a CUDA compiler:
export CUDACXX=$(which nvcc)
export CUDAHOSTCXX=$(which clang++)
From the base of the pyAMReX source directory, execute:
# optional controls (example):
#export AMREX_SPACEDIM=3
#export AMREX_MPI=ON
#export AMREX_OMP=ON
#export AMREX_GPU_BACKEND=CUDA
#export AMREX_SRC=$PWD/../amrex
#export CMAKE_BUILD_PARALLEL_LEVEL=8
# optional: --force-reinstall --user
python3 -m pip install -v .
If you are iterating on C++ builds, it might be faster to just call CMake:
cmake -S . -B build
cmake --build build -j 8 # repeat this step to fix compile errors
If you are using the pip-driven install, selected AMReX CMake options can be controlled with environment variables:
Environment Variable | Default & Values | Description |
---|---|---|
AMREX_OMP |
ON/OFF | Enable OpenMP |
AMREX_GPU_BACKEND |
NONE/SYCL/CUDA/HIP | On-node, accelerated GPU backend |
AMREX_MPI |
ON/OFF | Enable MPI |
AMREX_PRECISION |
SINGLE/DOUBLE | Precision of AMReX Real type |
AMREX_SPACEDIM |
1/2/3 | Dimension of AMReX |
AMREX_BUILD_SHARED_LIBS |
ON/OFF | Build the core AMReX library as shared library |
AMREX_SRC |
None | Absolute path to AMReX source directory (preferred if set) |
AMREX_REPO |
https://github.com/AMReX-Codes/amrex.git |
Repository URI to pull and build AMReX from |
AMREX_BRANCH |
development |
Repository branch for AMREX_REPO |
AMREX_INTERNAL |
ON/OFF | Needs a pre-installed AMReX library if set to OFF |
AMREX_LIBDIR |
None (note: not yet implemented) | If set, search for pre-built AMReX C++ libraries (see below) |
CMAKE_BUILD_PARALLEL_LEVEL |
2 | Number of parallel build threads |
For example, one can also build against a local AMReX copy.
Assuming AMReX' source is located in $HOME/src/amrex
, then export AMREX_SRC=$HOME/src/amrex
.
Or as a one-liner, assuming your AMReX source directory is located in ../amrex
:
AMREX_SRC=$PWD/../amrex python3 -m pip install -v --force-reinstall .
Note that you need to use absolute paths for external source trees, because pip builds in a temporary directory.
Or build against an AMReX feature branch of a colleague.
Assuming your colleague pushed AMReX to https://github.com/WeiqunZhang/amrex/
in a branch new-feature
then
unset AMREX_SRC # preferred if set
AMREX_REPO=https://github.com/WeiqunZhang/amrex.git AMREX_BRANCH=new-feature python3 -m pip install -v --force-reinstall .
You can speed up the install further if you pre-install AMReX, e.g. with a package manager.
Set AMREX_INTERNAL=OFF
and add installation prefix of AMReX to the environment variable CMAKE_PREFIX_PATH.
Please see the short CMake tutorial that we linked above if this sounds new to you.
pyAMReX Copyright (c) 2021, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.
If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Innovation & Partnerships Office at [email protected].
NOTICE. This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit other to do so.
License for pyamrex can be found at LICENSE.