Skip to content

Commit 3bf4acc

Browse files
ajnonakaajnonaka
authored
Merge pull request #140 from jmsexton03/readme_update_cmake
Add cmake installation and run instructions to readme
2 parents 412b90f + d961763 commit 3bf4acc

1 file changed

Lines changed: 171 additions & 32 deletions

File tree

‎README.md‎

Lines changed: 171 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -4,40 +4,179 @@ ARTEMIS (Adaptive mesh Refinement Time-domain ElectrodynaMIcs Solver) is a high-
44
For questions, please reach out to Zhi (Jackie) Yao (jackie_zhiyao@lbl.gov) and Andy Nonaka (ajnonaka@lbl.gov).
55

66
# Installation
7-
## Download AMReX Repository
8-
``` git clone git@github.com:AMReX-Codes/amrex.git ```
9-
## Download Artemis Repository
10-
``` git clone git@github.com:AMReX-Microelectronics/artemis.git ```
11-
## Build
12-
Make sure that the AMReX and Artemis are cloned in the same location in their filesystem. Navigate to the Exec folder of Artemis and execute
13-
```make -j 4```. <br />
14-
You can turn on and off the LLG equation by specifying ```USE_LLG``` during compilation. <br />
15-
The following command compiles Artemis without LLG
16-
```make -j 4 USE_LLG=FALSE``` <br />
17-
The following command compiles Artemis with LLG
18-
```make -j 4 USE_LLG=TRUE``` <br />
19-
The default value of ```USE_LLG``` is ```TRUE```.
7+
8+
## Prerequisites
9+
- C++ compiler with C++17 support (GCC, Clang, Intel, NVCC for GPU builds)
10+
- MPI implementation (OpenMPI, MPICH) - optional but recommended
11+
- CUDA Toolkit (for GPU builds) - optional
12+
- OpenMP (for CPU parallel builds) - optional
13+
- For CMake builds: CMake version 3.18 or higher
14+
- For GNU Make builds: GNU Make
15+
16+
## Download Repositories
17+
18+
### Download AMReX Repository
19+
```bash
20+
git clone https://github.com/AMReX-Codes/amrex.git
21+
```
22+
23+
### Download Artemis Repository
24+
```bash
25+
git clone https://github.com/AMReX-Microelectronics/artemis.git
26+
```
27+
28+
Make sure that AMReX and Artemis are cloned in the same location in their filesystem.
29+
30+
## Build Options
31+
32+
### Option 1: Build with GNU Make
33+
34+
Navigate to the Exec folder of Artemis and execute:
35+
36+
#### Basic build
37+
```bash
38+
make -j 4
39+
```
40+
41+
#### Build without LLG
42+
```bash
43+
make -j 4 USE_LLG=FALSE
44+
```
45+
46+
#### Build with LLG (default)
47+
```bash
48+
make -j 4 USE_LLG=TRUE
49+
```
50+
51+
#### GPU build with CUDA
52+
```bash
53+
make -j 4 USE_LLG=TRUE USE_GPU=TRUE
54+
```
55+
56+
The default value of `USE_LLG` is `TRUE`.
57+
58+
### Option 2: Build with CMake
59+
60+
Create a build directory and configure:
61+
62+
#### Basic CPU Build
63+
```bash
64+
cd artemis
65+
mkdir build && cd build
66+
cmake .. -DCMAKE_BUILD_TYPE=Release
67+
cmake --build . -j 4
68+
```
69+
70+
#### MPI + OpenMP Build
71+
```bash
72+
cmake -S . -B build \
73+
-DCMAKE_BUILD_TYPE=Release \
74+
-DWarpX_MPI=ON \
75+
-DWarpX_COMPUTE=OMP \
76+
-DWarpX_MAG_LLG=ON
77+
cmake --build build -j 4
78+
```
79+
80+
#### GPU Build with CUDA
81+
```bash
82+
cmake -S . -B build \
83+
-DCMAKE_BUILD_TYPE=Release \
84+
-DWarpX_COMPUTE=CUDA \
85+
-DWarpX_MPI=ON \
86+
-DWarpX_MAG_LLG=ON \
87+
-DAMReX_CUDA_ARCH=8.0 # Adjust for your GPU architecture
88+
cmake --build build -j 4
89+
```
90+
91+
#### Build without LLG
92+
```bash
93+
cmake -S . -B build \
94+
-DCMAKE_BUILD_TYPE=Release \
95+
-DWarpX_MAG_LLG=OFF
96+
cmake --build build -j 4
97+
```
98+
99+
### Common CMake Options
100+
- `-DWarpX_MAG_LLG=ON/OFF` - Enable/disable LLG equation (default: ON)
101+
- `-DWarpX_MPI=ON/OFF` - Enable/disable MPI (default: ON)
102+
- `-DWarpX_COMPUTE=NOACC/OMP/CUDA/SYCL` - Set compute backend
103+
- `-DWarpX_PRECISION=SINGLE/DOUBLE` - Set floating point precision
104+
- `-DWarpX_EB=ON/OFF` - Enable/disable embedded boundaries
105+
- `-DWarpX_OPENPMD=ON/OFF` - Enable/disable openPMD I/O
106+
- `-DCMAKE_BUILD_TYPE=Debug/Release` - Set build type
107+
108+
### AMReX Configuration Options
109+
110+
**AMReX Dependency Management:**
111+
```bash
112+
# Use external AMReX installation
113+
cmake -S . -B build \
114+
-DWarpX_amrex_internal=OFF \
115+
-DAMReX_DIR=/path/to/amrex/lib/cmake/AMReX
116+
117+
# Use local AMReX source directory
118+
cmake -S . -B build -DWarpX_amrex_src=/path/to/amrex/source
119+
120+
# Use custom AMReX repository/branch
121+
cmake -S . -B build \
122+
-DWarpX_amrex_repo=https://github.com/user/amrex.git \
123+
-DWarpX_amrex_branch=my_branch
124+
```
20125

21126
# Running Artemis
22-
Example input scripts are located in `Examples` directory.
23-
## Simple Testcase without LLG
24-
You can run the following to simulate an air-filled X-band rectangle waveguide:
25-
## For MPI+OMP build
26-
```make -j 4 USE_LLG=FALSE``` <br />
27-
```mpirun -n 4 ./main3d.gnu.TPROF.MTMPI.OMP.GPUCLOCK.ex Examples/Waveguide/inputs_3d_empty_X_band```
28-
## For MPI+CUDA build
29-
```make -j 4 USE_LLG=FALSE USE_GPU=TRUE``` <br />
30-
```mpirun -n 4 ./main3d.gnu.TPROF.MTMPI.CUDA.GPUCLOCK.ex Examples/Waveguide/inputs_3d_empty_X_band```
31-
## Simple Testcase with LLG
32-
You can run the following to simulate an X-band magnetically tunable filter:
33-
## For MPI+OMP build
34-
```make -j 4 USE_LLG=TRUE``` <br />
35-
```mpirun -n 8 ./main3d.gnu.TPROF.MTMPI.OMP.GPUCLOCK.ex Examples/Waveguide/inputs_3d_LLG_filter```
36-
## For MPI+CUDA build
37-
```make -j 4 USE_LLG=TRUE USE_GPU=TRUE``` <br />
38-
```mpirun -n 8 ./main3d.gnu.TPROF.MTMPI.CUDA.GPUCLOCK.ex Examples/Waveguide/inputs_3d_LLG_filter```
39-
# Visualization and Data Analysis
40-
Refer to the following link for several visualization tools that can be used for AMReX plotfiles.
127+
128+
Example input scripts are located in `Examples` directory.
129+
130+
## Running with GNU Make builds
131+
132+
### Simple Testcase without LLG
133+
For an air-filled X-band rectangle waveguide:
134+
135+
#### MPI+OMP build
136+
```bash
137+
make -j 4 USE_LLG=FALSE
138+
mpirun -n 4 ./main3d.gnu.TPROF.MTMPI.OMP.GPUCLOCK.ex Examples/Waveguide/inputs_3d_empty_X_band
139+
```
140+
141+
#### MPI+CUDA build
142+
```bash
143+
make -j 4 USE_LLG=FALSE USE_GPU=TRUE
144+
mpirun -n 4 ./main3d.gnu.TPROF.MTMPI.CUDA.GPUCLOCK.ex Examples/Waveguide/inputs_3d_empty_X_band
145+
```
146+
147+
### Simple Testcase with LLG
148+
For an X-band magnetically tunable filter:
149+
150+
#### MPI+OMP build
151+
```bash
152+
make -j 4 USE_LLG=TRUE
153+
mpirun -n 8 ./main3d.gnu.TPROF.MTMPI.OMP.GPUCLOCK.ex Examples/Waveguide/inputs_3d_LLG_filter
154+
```
155+
156+
#### MPI+CUDA build
157+
```bash
158+
make -j 4 USE_LLG=TRUE USE_GPU=TRUE
159+
mpirun -n 8 ./main3d.gnu.TPROF.MTMPI.CUDA.GPUCLOCK.ex Examples/Waveguide/inputs_3d_LLG_filter
160+
```
161+
162+
## Running with CMake builds
163+
164+
The CMake build produces executables in the build directory. The exact name depends on your configuration:
165+
166+
### Basic execution
167+
```bash
168+
./build/bin/warpx Examples/Waveguide/inputs_3d_empty_X_band
169+
```
170+
171+
### With MPI
172+
```bash
173+
mpirun -n 4 ./build/bin/warpx Examples/Waveguide/inputs_3d_LLG_filter
174+
```
175+
176+
### With GPU
177+
```bash
178+
mpirun -n 4 ./build/bin/warpx Examples/Waveguide/inputs_3d_LLG_filter
179+
```
41180

42181
[Visualization](https://amrex-codes.github.io/amrex/docs_html/Visualization_Chapter.html)
43182

0 commit comments

Comments
 (0)