Docs: fix bugs (broken links, missing examples) (#5522)

EZoni · web-flow · commit 9fdc6ecab546 · 2025-01-08T09:31:47.000-08:00
Just fixing a few errors and warnings I found while working on another documentation PR. Mostly broken links and missing examples. Merge #5523 first, see #5522 (comment) below.
diff --git a/Docs/source/developers/checksum.rst b/Docs/source/developers/checksum.rst
@@ -22,11 +22,6 @@ This relies on the function ``evaluate_checksum``:
 
 .. autofunction:: checksumAPI.evaluate_checksum
 
-Here's an example:
-
-.. literalinclude:: ../../../Examples/Tests/embedded_circle/analysis.py
-   :language: python
-
 This can also be included as part of an existing analysis script.
 
 How to evaluate checksums from the command line
diff --git a/Docs/source/developers/fields.rst b/Docs/source/developers/fields.rst
@@ -119,9 +119,9 @@ Bilinear filter
 
 The multi-pass bilinear filter (applied on the current density) is implemented in ``Source/Filter/``, and class ``WarpX`` holds an instance of this class in member variable ``WarpX::bilinear_filter``. For performance reasons (to avoid creating too many guard cells), this filter is directly applied in communication routines, see ``WarpX::AddCurrentFromFineLevelandSumBoundary`` above and
 
-.. doxygenfunction:: WarpX::ApplyFilterMF(const amrex::Vector<std::array<std::unique_ptr<amrex::MultiFab>, 3>> &mfvec, int lev, int idim)
+.. doxygenfunction:: WarpX::ApplyFilterMF(const ablastr::fields::MultiLevelVectorField &mfvec, int lev, int idim)
 
-.. doxygenfunction:: WarpX::SumBoundaryJ(const amrex::Vector<std::array<std::unique_ptr<amrex::MultiFab>, 3>> &current, int lev, int idim, const amrex::Periodicity &period)
+.. doxygenfunction:: WarpX::SumBoundaryJ(const ablastr::fields::MultiLevelVectorField &current, int lev, int idim, const amrex::Periodicity &period)
 
 Godfrey's anti-NCI filter for FDTD simulations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/Docs/source/developers/particles.rst b/Docs/source/developers/particles.rst
@@ -83,7 +83,7 @@ Main functions
 
 .. doxygenfunction:: PhysicalParticleContainer::PushPX
 
-.. doxygenfunction:: WarpXParticleContainer::DepositCurrent(amrex::Vector<std::array<std::unique_ptr<amrex::MultiFab>, 3>> &J, amrex::Real dt, amrex::Real relative_time)
+.. doxygenfunction:: WarpXParticleContainer::DepositCurrent(ablastr::fields::MultiLevelVectorField const &J, amrex::Real dt, amrex::Real relative_time)
 
 .. note::
    The current deposition is used both by ``PhysicalParticleContainer`` and ``LaserParticleContainer``, so it is in the parent class ``WarpXParticleContainer``.
diff --git a/Docs/source/install/hpc/dane.rst b/Docs/source/install/hpc/dane.rst
@@ -3,17 +3,17 @@
 Dane (LLNL)
 =============
 
-The `Dane Intel CPU cluster <https://hpc.llnl.gov/hardware/compute-platforms/dane>`_ is located at LLNL.
+The `Dane Intel CPU cluster <https://hpc.llnl.gov/hardware/compute-platforms/dane>`__ is located at LLNL.
 
 
 Introduction
 ------------
 
 If you are new to this system, **please see the following resources**:
 
-* `LLNL user account <https://lc.llnl.gov`__ (login required)
+* `LLNL user account <https://lc.llnl.gov>`__ (login required)
 * `Jupyter service <https://lc.llnl.gov/jupyter>`__ (`documentation <https://lc.llnl.gov/confluence/display/LC/JupyterHub+and+Jupyter+Notebook>`__, login required)
-* `Production directories <https://hpc.llnl.gov/hardware/file-systems>`_:
+* `Production directories <https://hpc.llnl.gov/hardware/file-systems>`__:
 
   * ``/p/lustre1/$(whoami)`` and ``/p/lustre2/$(whoami)``: personal directory on the parallel filesystem
   * Note that the ``$HOME`` directory and the ``/usr/workspace/$(whoami)`` space are NFS mounted and *not* suitable for production quality data generation.
diff --git a/Docs/source/install/hpc/lawrencium.rst b/Docs/source/install/hpc/lawrencium.rst
@@ -69,7 +69,7 @@ And since Lawrencium does not yet provide a module for them, install ADIOS2, BLA
    cmake -S src/lapackpp -B src/lapackpp-v100-build -DCMAKE_CXX_STANDARD=17 -Dgpu_backend=cuda -Dbuild_tests=OFF -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=ON -DCMAKE_INSTALL_PREFIX=$HOME/sw/v100/lapackpp-master -Duse_cmake_find_lapack=ON -DBLAS_LIBRARIES=${LAPACK_DIR}/lib/libblas.a -DLAPACK_LIBRARIES=${LAPACK_DIR}/lib/liblapack.a
    cmake --build src/lapackpp-v100-build --target install --parallel 12
 
-Optionally, download and install Python packages for :ref:`PICMI <usage-picmi>` or dynamic ensemble optimizations (:ref:`libEnsemble <libensemble>`):
+Optionally, download and install Python packages for :ref:`PICMI <usage-picmi>` or dynamic ensemble optimizations (`libEnsemble <https://libensemble.readthedocs.io/en/main/>`__):
 
 .. code-block:: bash
 
diff --git a/Docs/source/refs.bib b/Docs/source/refs.bib
@@ -458,6 +458,7 @@ @misc{Fallahi2020
 @article{VayFELA2009,
   title = {FULL ELECTROMAGNETIC SIMULATION OF FREE-ELECTRON LASER AMPLIFIER PHYSICS VIA THE LORENTZ-BOOSTED FRAME APPROACH},
   author = {Fawley, William M and Vay, Jean-Luc},
+  journal = {},
   abstractNote = {Numerical simulation of some systems containing charged particles with highly relativistic directed motion can by speeded up by orders of magnitude by choice of the proper Lorentz-boosted frame[1]. A particularly good example is that of short wavelength free-electron lasers (FELs) in which a high energy electron beam interacts with a static magnetic undulator. In the optimal boost frame with Lorentz factor gamma_F , the red-shifted FEL radiation and blue shifted undulator have identical wavelengths and the number of required time-steps (presuming the Courant condition applies) decreases by a factor of 2(gamma_F)**2 for fully electromagnetic simulation. We have adapted the WARP code [2]to apply this method to several FEL problems involving coherent spontaneous emission (CSE) from pre-bunched ebeams, including that in a biharmonic undulator.},
   url = {https://www.osti.gov/biblio/964405},
   place = {United States},
diff --git a/Docs/source/theory/multiphysics/collisions.rst b/Docs/source/theory/multiphysics/collisions.rst
@@ -131,7 +131,7 @@ The process is also the same as for elastic scattering except the excitation ene
 Benchmarks
 ----------
 
-See the :ref:`MCC example <examples-mcc-turner>` for a benchmark of the MCC
+See the :ref:`MCC example <examples-capacitive-discharge>` for a benchmark of the MCC
 implementation against literature results.
 
 Particle cooling due to elastic collisions
diff --git a/Docs/source/usage/examples.rst b/Docs/source/usage/examples.rst
@@ -65,14 +65,6 @@ Microelectronics
 * `ARTEMIS manual <https://artemis-em.readthedocs.io>`__
 
 
-Nuclear Fusion
---------------
-
-.. note::
-
-   TODO
-
-
 Fundamental Plasma Physics
 --------------------------
 
diff --git a/Docs/source/usage/examples/thomson_parabola_spectrometer b/Docs/source/usage/examples/thomson_parabola_spectrometer
@@ -0,0 +1 @@
+../../../../Examples/Physics_applications/thomson_parabola_spectrometer
diff --git a/Examples/Physics_applications/thomson_parabola_spectrometer/README.rst b/Examples/Physics_applications/thomson_parabola_spectrometer/README.rst
@@ -28,7 +28,7 @@ The PICMI input file is not available for this example yet.
 
 For `MPI-parallel <https://www.mpi-forum.org>`__ runs, prefix these lines with ``mpiexec -n 4 ...`` or ``srun -n 4 ...``, depending on the system.
 
-.. literalinclude:: inputs
+.. literalinclude:: inputs_test_3d_thomson_parabola_spectrometer
    :language: ini
    :caption: You can copy this file from ``Examples/Physics_applications/thomson_parabola_spectrometer/inputs_test_3d_thomson_parabola_spectrometer``.
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../../Examples/Physics_applications/thomson_parabola_spectrometer`