Skip to content

Commit ac79cc9

Browse files
jackieyao0114jackieyao0114
authored
Update run_artemis.rst
1 parent 9ebdc96 commit ac79cc9

File tree

1 file changed

+103
-26
lines changed

1 file changed

+103
-26
lines changed

‎Docs/source/usage/run_artemis.rst‎

Lines changed: 103 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,121 @@
1-
.. _running-artemis:
1+
.. _usage_run_artemis:
22

3-
Running ARTEMIS
4-
===============
3+
Run ARTEMIS
4+
===========
55

6-
This document demonstrates a few examples of how to **run ARTEMIS** after installation and compilation. Example input scripts reside in the ``Examples/`` directory.
6+
This page describes how to set up and run a simulation using ARTEMIS (Adaptive mesh Refinement Time-domain ElectrodynaMIcs Solver). With ARTEMIS, you can model electromagnetic fields using the finite-difference time-domain (FDTD) method as well as couple them to magnetization dynamics through the Landau–Lifshitz–Gilbert (LLG) equation.
77

8-
1. Simple Testcase without LLG
9-
------------------------------
8+
Steps to Run a New Simulation
9+
-----------------------------
1010

11-
Below is an air-filled X-band rectangular waveguide simulation.
11+
1. **Set up a Run Directory**
1212

13-
- **MPI + OpenMP Build**:
13+
On Linux/macOS, create a directory for your simulation:
1414

15-
.. code-block:: bash
15+
.. code-block:: bash
1616
17-
make -j 4 USE_LLG=FALSE
18-
mpirun -n 4 ./main3d.gnu.TPROF.MTMPI.OMP.GPUCLOCK.ex Examples/Waveguide/inputs_3d_empty_X_band
17+
mkdir -p <run_directory>
1918
20-
- **MPI + CUDA Build**:
19+
Replace ``<run_directory>`` with the path where you want to store the run outputs, input files, and executables.
2120

22-
.. code-block:: bash
21+
2. **Copy the ARTEMIS Executable**
2322

24-
make -j 4 USE_LLG=FALSE USE_GPU=TRUE
25-
mpirun -n 4 ./main3d.gnu.TPROF.MTMPI.CUDA.GPUCLOCK.ex Examples/Waveguide/inputs_3d_empty_X_band
23+
If you have already compiled ARTEMIS (see :ref:`install-artemis`), the executable (e.g., ``main3d.*.ex``) will reside in the ``Exec/`` folder under ``artemis``. Copy it to your run directory:
2624

27-
2. Simple Testcase with LLG
28-
---------------------------
25+
.. code-block:: bash
2926
30-
Below is a magnetically tunable X-band filter simulation.
27+
cp /path/to/artemis/Exec/<artemis_executable> <run_directory>/
3128
32-
- **MPI + OpenMP Build**:
29+
Here, ``<artemis_executable>`` should be replaced by the name of your compiled executable (for example, ``main3d.gnu.TPROF.MTMPI.OMP.GPUCLOCK.ex``).
3330

34-
.. code-block:: bash
31+
3. **Prepare an Input File**
3532

36-
make -j 4 USE_LLG=TRUE
37-
mpirun -n 8 ./main3d.gnu.TPROF.MTMPI.OMP.GPUCLOCK.ex Examples/Waveguide/inputs_3d_LLG_filter
33+
You will need an input file that specifies the numerical and physical parameters of your simulation. ARTEMIS reads input parameters via AMReX’s `ParmParse <https://amrex-codes.github.io/amrex/docs_html/Basics.html#parmparse>`_. These parameters include:
3834

39-
- **MPI + CUDA Build**:
35+
- **Domain geometry**: domain length, number of cells, etc.
36+
- **Electromagnetic solver settings**: time-step size, total time steps, output frequency, boundary conditions, source definitions (e.g. waveguide modes, plane-wave excitations).
37+
- **PML configuration**: absorbing boundary thickness, PML parameters.
38+
- **LLG options** (if using micromagnetics): magnetization field initialization, material parameters for exchange, damping, anisotropy, etc.
4039

41-
.. code-block:: bash
40+
Sample input files are available in ``artemis/Examples/``. For instance:
4241

43-
make -j 4 USE_LLG=TRUE USE_GPU=TRUE
44-
mpirun -n 8 ./main3d.gnu.TPROF.MTMPI.CUDA.GPUCLOCK.ex Examples/Waveguide/inputs_3d_LLG_filter
42+
.. code-block:: bash
43+
44+
cd <run_directory>
45+
cp /path/to/artemis/Examples/Waveguide/inputs_3d_empty_X_band ./my_inputs_file
46+
47+
You may then edit ``my_inputs_file`` to customize your simulation parameters.
48+
49+
4. **Run the ARTEMIS Executable**
50+
51+
To launch the simulation, navigate to your run directory and execute the ARTEMIS binary with the input file. For an MPI run, for example:
52+
53+
.. code-block:: bash
54+
55+
cd <run_directory>
56+
mpirun -np <n_ranks> ./<artemis_executable> my_inputs_file
57+
58+
- ``<n_ranks>``: number of MPI processes to use.
59+
- ``<artemis_executable>``: your ARTEMIS compiled binary (e.g. ``main3d.gnu.TPROF.MTMPI.CUDA.GPUCLOCK.ex``).
60+
61+
If you are using GPU acceleration, ensure your environment is correctly set up to use CUDA (or HIP). For instance, on some HPC systems you may need:
62+
63+
.. code-block:: bash
64+
65+
module load cuda
66+
mpirun -n <n_ranks> ./<artemis_executable> my_inputs_file
67+
68+
where CUDA driver/toolkit is loaded beforehand.
69+
70+
5. **Monitor the Simulation**
71+
72+
As the simulation runs, ARTEMIS will output status updates (e.g., current time step, maximum field values, or any warnings) to your terminal (stdout). On HPC systems, you often redirect this output to a file (for example, ``outputs.txt``) by including something like:
73+
74+
.. code-block:: bash
75+
76+
mpirun -n <n_ranks> ./<artemis_executable> my_inputs_file > outputs.txt
77+
78+
or using a job submission script if running on a batch scheduler (e.g., SLURM, LSF).
79+
80+
6. **Outputs and Plotfiles**
81+
82+
ARTEMIS typically writes data in **AMReX plotfile** format at specified intervals set in your input file (e.g., ``plot_int`` parameter). These plotfiles will be named something like ``plt0000100``, where the number refers to the time step. You can visualize these outputs with:
83+
84+
- `ParaView <https://www.paraview.org/>`_
85+
- `VisIt <https://wci.llnl.gov/simulation/computer-codes/visit>`_
86+
- `yt <https://yt-project.org/>`_ (using ``yt.load('plt0000100')``)
87+
88+
For instance, to visualize using ParaView, copy or link the ``plt0000XXX`` directory to your local machine (if running on HPC), open ParaView, and choose ``Open -> (your plotfile)``. ParaView recognizes the AMReX format and allows you to slice, colorize, or animate your fields in 3D.
89+
90+
7. **Common Parameters in ARTEMIS Input Files**
91+
92+
Although ARTEMIS shares many input parameters with other AMReX-based codes, some are specific to electromagnetic or micromagnetics simulations. Key options include:
93+
94+
- **Maxwell solver options**: time step size, Courant condition, update intervals.
95+
- **Boundary conditions**: `domain.is_periodic` or the specification of PML or conducting walls.
96+
- **Micromagnetics**: If ``USE_LLG=TRUE`` was enabled, the input file should include magnetization initialization and LLG-related coefficients (Gilbert damping, exchange constant, etc.).
97+
- **Output frequency**: e.g., ``plot_int = 100`` to write fields every 100 steps.
98+
99+
See examples in ``artemis/Examples/`` for detailed input parameters.
100+
101+
8. **Finalizing the Run**
102+
103+
Once the simulation reaches the final time step (or meets a stopping criterion), ARTEMIS writes the last plotfile and exits. If you are on an HPC system, you can check your job queue or the output file (e.g., ``outputs.txt``) to confirm the run completed successfully. The final plotfile often stores the full fields at the last time step for post-processing.
104+
105+
106+
Advanced Usage
107+
--------------
108+
109+
- **MPI + OpenMP**: If you built ARTEMIS with both MPI and OpenMP (`make -j 4 USE_OMP=TRUE`), you can control the number of OpenMP threads by setting ``OMP_NUM_THREADS``.
110+
- **Adaptive Mesh Refinement (AMR)**: If you use a multi-level input file (e.g., specifying `amr.n_level`), ARTEMIS will refine the mesh around regions of interest. Plotfiles will then show multiple levels of data.
111+
- **Micromagnetics**: When ``USE_LLG=TRUE``, additional array fields for magnetization components will be allocated, and the FDTD step will couple to LLG updates.
112+
- **Superconductivity**: Some versions of ARTEMIS allow modeling superconductors with a two-fluid model. Ensure your input file is set up properly, referencing the parameters introduced in the relevant publication or example.
113+
114+
Further Documentation
115+
---------------------
116+
117+
- :ref:`install-artemis` for building instructions and dependencies.
118+
- `ARTEMIS GitHub <https://github.com/AMReX-Microelectronics/artemis>`_ for source code, issues, and updates.
119+
- `Examples/ <https://github.com/AMReX-Microelectronics/artemis/tree/main/Examples>`_ directory for multiple sample scenarios (waveguide tests, magnetically tunable filters, superconducting resonators, etc.).
120+
121+
We welcome user contributions and feedback. If you encounter any problems or have feature requests, please open an issue on our `GitHub repository <https://github.com/AMReX-Microelectronics/artemis/issues>`_.

0 commit comments

Comments
 (0)