Doc: More Implementation Details (#195)

Add documentation pages that describe implementation specifics
in greater detail:
- Python module generation with pybind11
- zero-copy data interfaces

Author: ax3l

docs/source/acknowledge_us.rst

@@ -33,6 +33,11 @@ Further pyAMReX References
 
 Works using pyAMReX:
 
+- Huebl A et al.,
+  **Exascale and ML Models for Accelerator Simulations**.
+  presentation at the 6th European Advanced Accelerator Concepts workshop (EAAC23), Isola d'Elba, Italy, Sep 17 – 23, 2023.
+  `DOI:10.5281/zenodo.8362549 <https://doi.org/10.5281/zenodo.8362549>`__
+
 - 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.

docs/source/developers/implementation.rst

@@ -3,7 +3,19 @@
 Implementation Details
 ======================
 
-.. note::
+For now, please see these presentations:
 
-   TODO :-)
-   Link Dec 2022 slides from Axel or similar...
+- `A. Huebl et al., NREL virtual seminar, December 2022 <https://docs.google.com/presentation/d/1X3_OERbFcZEd-awNEEEoOd98VT-gmB1UDEfK7A4NgGc/edit?usp=sharing>`__
+- `A. Huebl et al., "Exascale and ML Models for Accelerator Simulations", 6th European Advanced Accelerator Concepts workshop (EAAC23), Isola d'Elba, Italy, Sep 17 – 23, 2023 DOI:10.5281/zenodo.8362549 <https://doi.org/10.5281/zenodo.8362549>`__
+
+
+Zero-Copy Data APIs
+-------------------
+
+pyAMReX implements the following `standardized data APIs <https://data-apis.org>`__:
+
+- ``__array_interface__`` (CPU)
+- ``__cuda_array_interface__`` (CUDA GPU)
+- ``DLPack`` (`coming soon <https://github.com/AMReX-Codes/pyamrex/issues/9#issuecomment-1644288546>`__)
+
+These APIs are automatically used when creating "views" (non-copy) numpy arrays, cupy arrays, PyTorch tensors, etc. from AMReX objects such as ``Array4`` and particle arrays.

docs/source/index.rst

@@ -20,7 +20,7 @@ The `pyAMReX GitHub repo <https://github.com/AMReX-Codes/pyamrex>`__ is the main
 Have a look at the action icons on the top right of the web page: feel free to watch the repo if you want to receive updates, or to star the repo to support the project.
 For bug reports or to request new features, you can also open a new `issue <https://github.com/AMReX-Codes/pyamrex/issues>`__.
 
-ON our `discussion page <https://github.com/ECP-WarpX/impactx/discussions>`__, you can find already answered questions, add new questions, get help with installation procedures, discuss ideas or share comments.
+On our `discussion page <https://github.com/AMReX-Codes/pyamrex/discussions>`__, you can find already answered questions, add new questions, get help with installation procedures, discuss ideas or share comments.
 
 .. raw:: html
 
@@ -65,6 +65,7 @@ Usage
 
    usage/how_to_run
    usage/api
+   usage/zerocopy
    usage/workflows
 ..   usage/tests
 

docs/source/usage/zerocopy.rst

@@ -0,0 +1,50 @@
+.. _usage-zerocopy:
+
+Zero-Copy
+=========
+
+pyAMReX is designed to bridge the worlds of block-structured codes and data science.
+As such, it includes zero-copy GPU data access for AI/ML, in situ analysis, application coupling by implementing :ref:`standardized data interfaces <developers-implementation`.
+
+
+CPU: numpy
+----------
+
+zero-copy read and write access.
+CPU as well as managed memory CPU/GPU.
+
+Call ``.to_numpy()`` on data objects of pyAMReX.
+See the optional arguments of this API.
+
+Writing to the created numpy array will also modify the underlying AMReX memory.
+
+
+GPU: cupy
+---------
+
+GPU zero-copy read and write access.
+
+Call ``.to_cupy()`` on data objects of pyAMReX.
+See the optional arguments of this API.
+
+Writing to the created cupy array will also modify the underlying AMReX memory.
+
+
+GPU: numba
+----------
+
+GPU zero-copy read and write access.
+
+After ``from numba import cuda``, create a zero-copy tensor on a GPU array via ``marr_numba = cuda.as_cuda_array(marr)``.
+
+Writing to the created numba array will also modify the underlying AMReX memory.
+
+
+AI/ML: pyTorch
+--------------
+
+CPU and GPU zero-copy read and write access.
+
+Create a zero-copy tensor on a GPU array via ``torch.as_tensor(amrex_array_here, device="cuda")``.
+
+Writing to the created PyTorch tensor will also modify the underlying AMReX memory.