[Draft] Docs

CODE_OF_CONDUCT.rst

@@ -0,0 +1,61 @@
+.. _coc:
+
+Code of Conduct
+===============
+
+Our Pledge
+----------
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+Our Standards
+-------------
+
+Examples of behavior that contributes to creating a positive environment include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+Our Responsibilities
+--------------------
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+Scope
+-----
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
+Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+Representation of a project may be further defined and clarified by project maintainers.
+
+Enforcement
+-----------
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [email protected].
+All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
+The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+Attribution
+-----------
+
+This Code of Conduct is adapted from the `Contributor Covenant <https://www.contributor-covenant.org>`_, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

docs/source/acknowledge_us.rst

@@ -0,0 +1,46 @@
+Acknowledge pyAMReX
+===================
+
+Please acknowledge the role that pyAMReX played in your research.
+
+
+In Publications
+***************
+
+If a project using pyAMReX leads to a scientific publication, please consider citing it.
+This helps to keep in touch with the community, shows its use and supports the project.
+
+.. code-block:: latex
+
+  \usepackage{hyperref}
+  This research used the open-source code pyAMReX \url{https://github.com/AMReX-Codes/pyamrex}.
+  We acknowledge all AMReX contributors.
+
+
+- Huebl A, Ananthan S, Grote D P, Sandberg R T, Zoni E, Lehe R, Jambunathan R, Myers A, Zhang W.
+  **pyAMReX**.
+  *software*, 2023.
+  `github.com/AMReX-Codes/pyamrex <https://github.com/AMReX-Codes/pyamrex>`__
+
+You can also add an acknowledgement, e.g.,
+
+  This research used the open-source code pyAMReX [citation].
+  We acknowledge all AMReX contributors.
+
+
+Further pyAMReX References
+**************************
+
+Works using pyAMReX:
+
+- Sandberg R T, Lehe R, Mitchell C E, Garten M, Qiang J, Vay J-L and Huebl A.
+  **Hybrid Beamline Element ML-Training for Surrogates in the ImpactX Beam-Dynamics Code**.
+  14th International Particle Accelerator Conference (IPAC'23), WEPA101, *in print*, 2023.
+  `preprint <https://www.ipac23.org/preproc/pdf/WEPA101.pdf>`__,
+  `DOI:10.18429/JACoW-IPAC-23-WEPA101 <https://doi.org/10.18429/JACoW-IPAC-23-WEPA101>`__
+
+- Huebl A, Lehe R, Mitchell C E, Qiang J, Ryne R D, Sandberg R T, Vay JL.
+  **Next Generation Computational Tools for the Modeling and Design of Particle Accelerators at Exascale**.
+  2022 North American Particle Accelerator Conference (NAPAC'22), TUYE2, pp. 302-306, 2022.
+  `arXiv:2208.02382 <https://arxiv.org/abs/2208.02382>`__,
+  `DOI:10.18429/JACoW-NAPAC2022-TUYE2 <https://doi.org/10.18429/JACoW-NAPAC2022-TUYE2>`__

docs/source/acknowledgements.rst

@@ -0,0 +1,4 @@
+Funding and Acknowledgements
+============================
+
+This work was supported by the Laboratory Directed Research and Development Program of Lawrence Berkeley National Laboratory under U.S. Department of Energy Contract No. DE-AC02-05CH11231.

docs/source/coc.rst

@@ -0,0 +1 @@
+../../CODE_OF_CONDUCT.rst

docs/source/conf.py

@@ -31,7 +31,9 @@
 import sphinx_rtd_theme  # noqa
 
 # path to .pyi files w/o having them installed
-sys.path.insert(0, os.path.join(os.path.abspath(__file__), "../src"))
+sys.path.insert(
+    0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "../../src")
+)
 
 # -- General configuration ------------------------------------------------
 

docs/source/glossary.rst

@@ -0,0 +1,9 @@
+.. _glossary:
+
+Glossary
+========
+
+In daily communication, we tend to abbreviate a lot of terms.
+It is important to us to make it easy to interact with the pyAMReX community and thus, this list shall help to clarify often used terms.
+
+Please see: https://warpx.readthedocs.io/en/latest/glossary.html

docs/source/install/cmake.rst

@@ -0,0 +1,172 @@
+.. _install-developers:
+.. _building-cmake:
+.. _building-cmake-intro:
+
+Developers
+==========
+
+`CMake <https://cmake.org>`_ is our primary build system.
+If you are new to CMake, `this short tutorial <https://hsf-training.github.io/hsf-training-cmake-webpage/>`_ from the HEP Software foundation is the perfect place to get started.
+If you just want to use CMake to build the project, jump into sections `1. Introduction <https://hsf-training.github.io/hsf-training-cmake-webpage/01-intro/index.html>`__, `2. Building with CMake <https://hsf-training.github.io/hsf-training-cmake-webpage/02-building/index.html>`__ and `9. Finding Packages <https://hsf-training.github.io/hsf-training-cmake-webpage/09-findingpackages/index.html>`__.
+
+Dependencies
+------------
+
+Before you start, you will need a copy of the pyAMReX source code:
+
+.. code-block:: bash
+
+   git clone https://github.com/AMReX-Codes/pyamrex.git $HOME/src/pyamrex
+   cd $HOME/src/pyamrex
+
+pyAMReX depends on popular third party software.
+On your development machine, :ref:`follow the instructions here <install-dependencies>`.
+
+.. toctree::
+   :hidden:
+
+   dependencies
+
+.. note::
+
+   Preparation: make sure you work with up-to-date Python tooling.
+
+   .. code-block:: bash
+
+      python3 -m pip install -U pip setuptools wheel pytest
+      python3 -m pip install -U -r requirements.txt
+
+
+Compile
+-------
+
+From the base of the pyAMReX source directory, execute:
+
+.. code-block:: bash
+
+   # find dependencies & configure
+   cmake -S . -B build -DAMReX_SPACEDIM="1;2;3"
+
+   # compile & install, here we use four threads
+   cmake --build build -j 4 --target pip_install
+
+That's all!
+
+You can inspect and modify build options after running ``cmake -S . -B build`` with either
+
+.. code-block:: bash
+
+   ccmake build
+
+or by adding arguments with ``-D<OPTION>=<VALUE>`` to the first CMake call, e.g.:
+
+.. code-block:: bash
+
+   cmake -S . -B build -DAMREX_GPU_BACKEND=CUDA -DAMREX_MPI=OFF -DAMReX_SPACEDIM="1;2;3"
+
+**That's it!**
+
+Developers could now change the pyAMReX source code and then call the install lines again to refresh the installation.
+
+.. tip::
+
+   If you do *not* develop with :ref:`a user-level package manager <install-dependencies>`, e.g., because you rely on a HPC system's environment modules, then consider to set up a virtual environment via `Python venv <https://docs.python.org/3/library/venv.html>`__.
+
+
+Build Options
+-------------
+
+=============================== ============================================ ===========================================================
+CMake Option                    Default & Values                             Description
+=============================== ============================================ ===========================================================
+``BUILD_TESTING``               **ON**/OFF                                   Build tests
+``CMAKE_BUILD_TYPE``            RelWithDebInfo/**Release**/Debug             Type of build, symbols & optimizations
+``CMAKE_INSTALL_PREFIX``        system-dependent path                        Install path prefix
+``CMAKE_VERBOSE_MAKEFILE``      ON/**OFF**                                   Print all compiler commands to the terminal during build
+``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``              ``3``                                        Dimension(s) of AMReX as a ``;``-separated list
+``AMReX_BUILD_SHARED_LIBS``     ON/**OFF**                                   Build AMReX library as shared (required for app extensions)
+``pyAMReX_IPO``                 **ON**/OFF                                   Compile with interprocedural/link optimization (IPO/LTO)
+``PYINSTALLOPTIONS``            *None*                                       Additional options for ``pip install``, e.g., ``-v --user``
+``Python_EXECUTABLE``           (newest found)                               Path to Python executable
+=============================== ============================================ ===========================================================
+
+pyAMReX can be configured in further detail with options from AMReX, which are documented in the AMReX manual:
+
+* `general AMReX build options <https://amrex-codes.github.io/amrex/docs_html/BuildingAMReX.html#customization-options>`__
+* `GPU-specific options <https://amrex-codes.github.io/amrex/docs_html/GPU.html#building-gpu-support>`__.
+
+**Developers** might be interested in additional options that control dependencies of pyAMReX.
+By default, the most important dependencies of pyAMReX are automatically downloaded for convenience:
+
+============================= ============================================== ===========================================================
+CMake Option                  Default & Values                               Description
+============================= ============================================== ===========================================================
+``BUILD_SHARED_LIBS``         ON/**OFF**                                     Build shared libraries for dependencies
+``CCACHE_PROGRAM``            First found ``ccache`` executable.             Set to ``-DCCACHE_PROGRAM=NO`` to disable CCache.
+``pyAMReX_amrex_src``         *None*                                         Path to AMReX source directory (preferred if set)
+``pyAMReX_amrex_repo``        ``https://github.com/AMReX-Codes/amrex.git``   Repository URI to pull and build AMReX from
+``pyAMReX_amrex_branch``      *we set and maintain a compatible commit*      Repository branch for ``pyAMReX_amrex_repo``
+``pyAMReX_amrex_internal``    **ON**/OFF                                     Needs a pre-installed AMReX library if set to ``OFF``
+``pyAMReX_pybind11_src``      *None*                                         Path to pybind11 source directory (preferred if set)
+``pyAMReX_pybind11_repo``     ``https://github.com/pybind/pybind11.git``     Repository URI to pull and build pybind11 from
+``pyAMReX_pybind11_branch``   *we set and maintain a compatible commit*      Repository branch for ``pyAMReX_pybind11_repo``
+``pyAMReX_pybind11_internal`` **ON**/OFF                                     Needs a pre-installed pybind11 module if set to ``OFF``
+============================= ============================================== ===========================================================
+
+For example, one can also build against a local AMReX copy.
+Assuming AMReX' source is located in ``$HOME/src/amrex``, add the ``cmake`` argument ``-DpyAMReX_amrex_src=$HOME/src/amrex``.
+Relative paths are also supported, e.g. ``-DpyAMReX_amrex_src=../amrex``.
+
+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 pass to ``cmake`` the arguments: ``-DpyAMReX_amrex_repo=https://github.com/WeiqunZhang/amrex.git -DpyAMReX_amrex_branch=new-feature``.
+
+You can speed up the install further if you pre-install these dependencies, e.g. with a package manager.
+Set ``-DpyAMReX_<dependency-name>_internal=OFF`` and add installation prefix of the dependency to the environment variable `CMAKE_PREFIX_PATH <https://cmake.org/cmake/help/latest/envvar/CMAKE_PREFIX_PATH.html>`__.
+Please see the :ref:`introduction to CMake <building-cmake-intro>` if this sounds new to you.
+
+If you re-compile often, consider installing the `Ninja <https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages>`__ build system.
+Pass ``-G Ninja`` to the CMake configuration call to speed up parallel compiles.
+
+
+Configure Your Compiler
+-----------------------
+
+If you don't want to use your default compiler, you can set the following environment variables.
+For example, using a Clang/LLVM:
+
+.. code-block:: bash
+
+   export CC=$(which clang)
+   export CXX=$(which clang++)
+
+If you also want to select a CUDA compiler:
+
+.. code-block:: bash
+
+   export CUDACXX=$(which nvcc)
+   export CUDAHOSTCXX=$(which clang++)
+
+.. note::
+
+   Please clean your build directory with ``rm -rf build/`` after changing the compiler.
+   Now call ``cmake -S . -B build`` (+ further options) again to re-initialize the build configuration.
+
+
+Run
+---
+
+We provide the public imports ``amrex.space1d``, ``amrex.space2d`` and ``amrex.space3d``, mirroring the compile-time option ``AMReX_SPACEDIM``.
+
+Due to limitations in AMReX, currently, only one of the imports can be used at a time in the same Python process.
+For example:
+
+.. code-block:: python
+
+   import amrex.space3d as amr
+
+A 1D or 2D AMReX run needs its own Python process.
+Another dimensionality *cannot be imported into the same Python process* after choosing a specific dimensionality for import.