diff --git a/README.md b/README.md index 4445ab533..5c438e774 100644 --- a/README.md +++ b/README.md @@ -1,154 +1,131 @@ -# ImpactX +# Differentiable ImpactX -[![CI Status](https://github.com/BLAST-ImpactX/impactx/actions/workflows/ubuntu.yml/badge.svg)](https://github.com/BLAST-ImpactX/impactx/actions/workflows/ubuntu.yml) -[![Documentation Status](https://readthedocs.org/projects/impactx/badge/?version=latest)](https://impactx.readthedocs.io) -[![License ImpactX](https://img.shields.io/badge/license-BSD--3--Clause--LBNL-blue.svg)](https://spdx.org/licenses/BSD-3-Clause-LBNL.html) -[![Supported Platforms](https://img.shields.io/badge/platforms-linux%20|%20osx%20|%20win-blue)](https://impactx.readthedocs.io/en/latest/install/users.html) -[![DOI (source)](https://img.shields.io/badge/DOI%20(source)-10.5281/zenodo.6954922-blue.svg)](https://doi.org/10.5281/zenodo.6954922) -[![DOI (paper)](https://img.shields.io/badge/DOI%20(paper)-10.18429%2FJACoW--NAPAC2022--TUYE2-blue.svg)](https://doi.org/10.18429/JACoW-NAPAC2022-TUYE2) -[![Language: C++17](https://img.shields.io/badge/language-C%2B%2B17-orange.svg)](https://isocpp.org/) -[![Language: Python](https://img.shields.io/badge/language-Python-orange.svg)](https://python.org/) +## Prepare Developer Environment (Ubuntu 24.02 w/ Clang/LLVM 16) -ImpactX: an s-based beam dynamics code including space charge effects. -This is the next generation of the [IMPACT-Z](https://github.com/impact-lbl/IMPACT-Z) code. - -## Documentation - -In order to learn how to install and run the code, please see the online documentation: -https://impactx.readthedocs.io - -* ImpactX Doxygen: https://impactx.readthedocs.io/en/latest/_static/doxyhtml -* AMReX Doxygen: https://amrex-codes.github.io/amrex/doxygen -* WarpX Doxygen: https://warpx.readthedocs.io/en/latest/_static/doxyhtml - -## Contributing +### Once +```bash +# Ref: https://github.com/EnzymeAD/enzyme-dev-docker/blob/main/Dockerfile +sudo apt install llvm-dev clang-16 lld-16 zlib1g-dev libzstd-dev git automake autoconf cmake make lldb-16 ninja-build build-essential libtool llvm-16-dev libclang-16-dev libomp-16-dev libblas-dev libeigen3-dev libboost-dev python3 +python3 -m pip install --break-system-package pipx pathlib2 +python3 -m pipx install lit cmake + +export CC="clang-16" +export CXX="clang++-16" + +# Ref: https://enzyme.mit.edu/Installation/ +git clone https://github.com/EnzymeAD/Enzyme ~/src/Enzyme +cd ~/src/Enzyme +cmake --fresh -G Ninja -S enzyme -B build -DLLVM_DIR=/usr/lib/llvm-16/lib/cmake/llvm -DLLVM_EXTERNAL_LIT=$(which lit) +cmake --build build -j 6 + +cd build +ninja check-enzyme + +# linker and lld and lto enforcement in CMake is hard... +cd .. +mkdir mylld +cd mylld +ln -s /usr/lib/llvm-16/bin/lld-link lld +ln -s $(which ld.lld-16) ld.lld # note: not sufficient yet... somehow hard-coded in compiler detection... use docker + # manually linking /usr/bin/ld.lld-16 as /usr/bin/ld.lld works... +export PATH=$PWD:$PATH + +# optional: create a venv for Python +rm -rf ~/src/venv-impactx-enzyme +python3 -m venv ~/src/venv-impactx-enzyme +source ~/src/venv-impactx-enzyme/bin/activate +python3 -m pip install --upgrade pip +python3 -m pip install --upgrade scipy numpy packaging setuptools[core] wheel pytest pytest-benchmark matplotlib PyQt6 +``` -[![AMReX](https://img.shields.io/static/v1?label="runs%20on"&message="AMReX"&color="blueviolet")](https://amrex-codes.github.io/) -Our workflow is described in [CONTRIBUTING.rst](CONTRIBUTING.rst). +## Compile Options -## Developer Environment +From the [homepage](https://enzyme.mit.edu/getting_started/UsingEnzyme/): +> Enzyme supports differentiating C/C++ code through ClangEnzyme and LLDEnzyme as compiler and linker plugins, respectively. +> Clang gives our plugin more flexibility in adding and ordering optimization passes than LLD and therefore using ClangEnzyme could result in better performance than LLDEnzyme. +> However, ClangEnzyme can only differentiate one compilation unit at a time and will therefore fail if the function which you try to differentiate calls functions in other compilation units (generally other .c or .cpp files). +> In these cases we recommend the use of LLDEnzyme in combination with LTO. -Please see our [developer installation section](https://impactx.readthedocs.io/en/latest/install/dependencies.html#install-dependencies) of the documentation for an easy install of our software dependencies. -## Get the Source Code +## Compile (ClangEnzyme, one TU) -Before you start, you will need a copy of the ImpactX source code: +### Always ```bash -git clone git@github.com:BLAST-ImpactX/impactx.git -cd impactx +source ~/src/venv-impactx-enzyme/bin/activate +alias cmake=$HOME/.local/pipx/venvs/cmake/bin/cmake +export CC="clang-16" +export CXX="clang++-16" + +# one TU: Clang Plugin +# Extra Enzyme options, e.g., print https://enzyme.mit.edu/getting_started/UsingEnzyme/#semantic-options +# optional add for verbose output: -mllvm -enzyme-print +export CXXFLAGS="-fplugin=$HOME/src/Enzyme/build/Enzyme/ClangEnzyme-16.so" ``` -## Compile - +With the active developer env above, inside the ImpactX source dir: ```bash -# find dependencies & configure -cmake -S . -B build - -# compile -cmake --build build -j 4 +cmake --fresh \ + -S . \ + -B build \ + -DImpactX_UNITY_BUILD=ON \ + -DImpactX_MPI=OFF \ + -DImpactX_COMPUTE=NOACC \ + -DImpactX_OPENPMD=OFF \ + -DCMAKE_LINKER_TYPE=LLD \ + -DCMAKE_LINKER=/usr/lib/llvm-16/bin/lld-link +# optional: +# -DImpactX_PYTHON=ON -DpyAMReX_IPO=OFF -DImpactX_PYTHON_IPO=OFF + +cmake --build build -j 6 + +# optional: +cmake --build build -j 6 --target pip_install ``` -That's all! -ImpactX binaries are now in `build/bin/`. -Most people execute these binaries directly or copy them out. -You can inspect and modify build options after running `cmake -S . -B` build with either +## Compile (LLDEnzyme, multiple TUs) -```bash -ccmake build -``` +TODO: redo this part using https://github.com/EnzymeAD/enzyme-dev-docker because ld, lld, ld.ldd with the non-system default is too tricky to get right in CMake (i.e. compiler detection). -or by adding arguments with `-D