Skip to content

Commit 94e2ee6

Browse files
ajnonakaajnonaka
authored
Merge pull request #4 from jmsexton03/restructure_and_add_build_info
Restructure and add build info
2 parents d08013b + 8441cad commit 94e2ee6

File tree

10 files changed

+1000
-102
lines changed

10 files changed

+1000
-102
lines changed

‎Docs/requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ picmistandard==0.23.2
1717
pygments
1818
recommonmark
1919
sphinx>=5.3
20+
sphinx-copybutton
2021
sphinx-design
2122
sphinx_rtd_theme>=1.1.1
2223
sphinxcontrib-bibtex

‎Docs/source/conf.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848
'sphinx.ext.napoleon',
4949
'sphinx.ext.viewcode',
5050
'sphinx_design',
51+
'sphinx_copybutton',
5152
'breathe',
5253
'sphinxcontrib.bibtex'
5354
]
@@ -59,6 +60,9 @@
5960
bibtex_bibfiles = ['./refs.bib']
6061
bibtex_default_style = 'unsrt'
6162

63+
# sphinx-copybutton configuration
64+
copybutton_exclude = '.linenos, .gp, .go'
65+
6266
# The suffix(es) of source filenames.
6367
# You can specify multiple suffix as a list of string:
6468
#

‎Docs/source/install/artemis.rst‎

Lines changed: 166 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -15,45 +15,190 @@ The code couples magnetization physics with electromagnetic fields in a temporal
1515
Installation
1616
------------
1717

18-
1. **Clone AMReX** (dependency):
18+
Quick Start
19+
~~~~~~~~~~~
1920

20-
.. code-block:: bash
21+
AMReX and ARTEMIS must be cloned in the same directory.
2122

22-
git clone git@github.com:AMReX-Codes/amrex.git
23+
.. code-block:: bash
2324
24-
2. **Clone ARTEMIS** in the same directory as AMReX:
25+
git clone https://github.com/AMReX-Codes/amrex.git
26+
git clone https://github.com/AMReX-Microelectronics/artemis.git
27+
cd artemis/
28+
make -j 4
2529
26-
.. code-block:: bash
30+
Detailed Installation Process
31+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2732

28-
git clone git@github.com:AMReX-Microelectronics/artemis.git
33+
Prerequisites and Dependencies
34+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2935

30-
Make sure ``amrex/`` and ``artemis/`` are placed alongside each other in your filesystem.
36+
ARTEMIS requires AMReX as its core dependency. The AMReX library provides the adaptive mesh refinement framework that enables ARTEMIS's high-performance capabilities. Both repositories must be placed alongside each other in your filesystem for the build system to locate the dependencies correctly.
3137

32-
3. **Build ARTEMIS**:
38+
Obtaining the Source Code
39+
^^^^^^^^^^^^^^^^^^^^^^^^^^
3340

34-
1. Navigate to the ``Exec/`` folder inside ``artemis/``.
35-
2. Build with ``make -j 4``, for example:
41+
Clone both AMReX and ARTEMIS from their respective GitHub repositories:
3642

37-
.. code-block:: bash
43+
.. code-block:: bash
3844
39-
cd artemis/Exec/
40-
make -j 4
45+
git clone https://github.com/AMReX-Codes/amrex.git
46+
git clone https://github.com/AMReX-Microelectronics/artemis.git
4147
42-
By default, *LLG* is enabled (``USE_LLG = TRUE``). You can explicitly switch it on/off:
48+
Ensure the directory structure appears as:
4349

44-
- **Without LLG**:
50+
.. code-block:: text
4551
46-
.. code-block:: bash
52+
parent_directory/
53+
├── amrex/
54+
└── artemis/
4755
48-
make -j 4 USE_LLG=FALSE
56+
Understanding the Build System
57+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4958

50-
- **With LLG**:
59+
ARTEMIS supports both GNU Make and CMake build systems. The choice depends on your preference and platform requirements:
5160

52-
.. code-block:: bash
61+
- **GNU Make**: Simpler configuration, suitable for development and testing
62+
- **CMake**: More flexible, better for complex builds and integration with other tools
5363

54-
make -j 4 USE_LLG=TRUE
64+
Key build flags control physics models and performance optimizations:
5565

56-
To enable GPU acceleration (e.g., CUDA), set ``USE_GPU=TRUE`` in the make command. Check the ``GNUmakefile`` or other build scripts for additional optional flags like MPI, OpenMP, etc.
66+
- **Physics Flags**: ``USE_LLG`` (GNU Make) or ``WarpX_MAG_LLG`` (CMake) enable the Landau-Lifshitz-Gilbert equation for ferromagnetic dynamics
67+
- **Performance Flags**: ``USE_GPU`` (GNU Make) or ``WarpX_COMPUTE`` (CMake) control hardware acceleration
68+
69+
Standard Build Process
70+
^^^^^^^^^^^^^^^^^^^^^^^
71+
72+
For GNU Make builds, navigate to the execution directory and compile:
73+
74+
.. code-block:: bash
75+
76+
cd artemis/
77+
make -j 4
78+
79+
For CMake builds, create a separate build directory:
80+
81+
.. code-block:: bash
82+
83+
cd artemis
84+
mkdir build && cd build
85+
cmake .. -DCMAKE_BUILD_TYPE=Release
86+
cmake --build . -j 4
87+
88+
Both methods produce an executable ready for simulation. By default, the Landau-Lifshitz-Gilbert equation is enabled, allowing for magnon-photon coupling simulations.
89+
90+
Build Verification
91+
^^^^^^^^^^^^^^^^^^
92+
93+
After successful compilation, verify the build by running a test simulation. The executable will be located in the build directory or top directory depending on your build method.
94+
95+
For detailed instructions on setting up and running ARTEMIS simulations, see :ref:`usage_run_artemis`.
96+
97+
Advanced Build Options
98+
-----------------------
99+
100+
Alternative Build Systems
101+
~~~~~~~~~~~~~~~~~~~~~~~~~~
102+
103+
**GNU Make with Custom Flags:**
104+
105+
Disable LLG physics:
106+
107+
.. code-block:: bash
108+
109+
make -j 4 USE_LLG=FALSE
110+
111+
Enable GPU acceleration:
112+
113+
.. code-block:: bash
114+
115+
make -j 4 USE_GPU=TRUE
116+
117+
**CMake with Explicit Control:**
118+
119+
Disable LLG equation:
120+
121+
.. code-block:: bash
122+
123+
cmake -S . -B build \
124+
-DCMAKE_BUILD_TYPE=Release \
125+
-DWarpX_MAG_LLG=OFF
126+
cmake --build build -j 4
127+
128+
Performance Optimizations
129+
~~~~~~~~~~~~~~~~~~~~~~~~~~
130+
131+
**MPI + OpenMP Build:**
132+
133+
.. code-block:: bash
134+
135+
cmake -S . -B build \
136+
-DCMAKE_BUILD_TYPE=Release \
137+
-DWarpX_MPI=ON \
138+
-DWarpX_COMPUTE=OMP \
139+
-DWarpX_MAG_LLG=ON
140+
cmake --build build -j 4
141+
142+
**GPU Build with CUDA:**
143+
144+
.. code-block:: bash
145+
146+
cmake -S . -B build \
147+
-DCMAKE_BUILD_TYPE=Release \
148+
-DWarpX_COMPUTE=CUDA \
149+
-DWarpX_MPI=ON \
150+
-DWarpX_MAG_LLG=ON \
151+
-DAMReX_CUDA_ARCH=8.0 # Adjust for your GPU architecture
152+
cmake --build build -j 4
153+
154+
Compile-Time Configuration Options
155+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156+
157+
**Common CMake Options:**
158+
159+
- ``-DWarpX_MAG_LLG=ON/OFF`` - Enable/disable LLG equation (default: ON)
160+
- ``-DWarpX_EB=ON/OFF`` - Enable/disable embedded boundaries
161+
- ``-DWarpX_OPENPMD=ON/OFF`` - Enable/disable openPMD I/O
162+
- ``-DWarpX_PRECISION=SINGLE/DOUBLE`` - Set floating point precision
163+
- ``-DCMAKE_BUILD_TYPE=Debug/Release`` - Set build type
164+
- ``-DWarpX_MPI=ON/OFF`` - Enable/disable MPI (default: ON)
165+
- ``-DWarpX_COMPUTE=NOACC/OMP/CUDA/SYCL`` - Set compute backend
166+
167+
**Debug Build Example:**
168+
169+
.. code-block:: bash
170+
171+
cmake -S . -B build \
172+
-DCMAKE_BUILD_TYPE=Debug \
173+
-DWarpX_MAG_LLG=ON
174+
cmake --build build -j 4
175+
176+
Platform-Specific Configurations
177+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
178+
179+
**External AMReX Installation:**
180+
181+
.. code-block:: bash
182+
183+
cmake -S . -B build \
184+
-DWarpX_amrex_internal=OFF \
185+
-DAMReX_DIR=/path/to/amrex/lib/cmake/AMReX
186+
187+
**Local AMReX Source Directory:**
188+
189+
.. code-block:: bash
190+
191+
cmake -S . -B build -DWarpX_amrex_src=/path/to/amrex/source
192+
193+
*Note: For GNU Make builds, set* ``AMREX_HOME`` *in the GNUmakefile.*
194+
195+
**Custom AMReX Repository/Branch:**
196+
197+
.. code-block:: bash
198+
199+
cmake -S . -B build \
200+
-DWarpX_amrex_repo=https://github.com/user/amrex.git \
201+
-DWarpX_amrex_branch=my_branch
57202
58203
Visualization and Data Analysis
59204
-------------------------------

0 commit comments

Comments
 (0)