Lorentz miniapp documentation

src/electromagnetics.md

@@ -478,5 +478,85 @@ to specify these regions. To change these, search the code for `std::map<int, do
 integer attribute to the floating-point material value.
 
 
+## Particle Trajectory Calculation
+
+Particle trajectory calculations are an important part of the Particle-In-Cell
+method but they can also provide an illuminating view of electromagnetic fields
+which can otherwise be difficult to visualize.
+
+### Lorentz Mini Application
+
+The Lorentz mini application approximates the trajectory of an individual
+particle using the explicit Boris algorithm. The equations being solved track
+the position and momentum of a particle with a given mass and charge.
+
+$$\begin{align}
+  \frac{d\vec{x}}{dt} & = \frac{\vec{p}}{m} \\\\
+  \frac{d\vec{p}}{dt} & =
+  q\left(\E + \frac{1}{m}\vec{p}\times\B\right)
+\end{align}$$
+
+The Boris algorithm, while not a symplectic method, provides long term accuracy
+by conserving volume in phase space. The algorithm updates the position in a single step but splits the momentum update into multiple steps:
+
+$$\begin{align}
+  \vec{p}\_- & = \vec{p}\_k + \frac{q \Delta t}{2} \E\_k \\\\
+  \vec{p}\_+ - \vec{p}\_- & =
+  \frac{q \Delta t}{2 m} \left(\vec{p}\_+ + \vec{p}\_-\right)\times\B\_k
+  \label{boris2} \\\\
+  \vec{p}\_{k+1} & = \vec{p}\_+ + \frac{q \Delta t}{2} \E\_k \\\\
+  \vec{x}\_{k+1} & = \vec{x}\_k + \frac{\Delta t}{m} \vec{p}\_{k+1}
+\end{align}$$
+
+While equation \eqref{boris2} may appear to be implicit it is clearly a linear
+equation so a small amount of algebra will produce an explicit, though more
+messy and less intuitive, formula.
+
+[![](img/examples/lorentz.png)](img/examples/lorentz.png)
+
+The above image shows a trajectory computed by the Lorentz mini application
+for a charged particle in the presence of a strong bar magnet and a relatively
+weak charged sphere. The trajectory exhibits the magnetic mirror effect where
+the higher magnetic field density near the poles causes the helical orbits to
+tighten and eventually reflect back towards the opposite pole.
+
+#### Mini Application Features
+
+**Electric Field:** The electric field is assumed to be zero unless a
+  VisItDataCollection is provided. The command line option `-er` can be used
+  to set the root name of the data collection e.g. `-er Volta-AMR-Parallel`.
+  The field name within the data collection is assumed to be `E` unless
+  overridden with `-ef`. The cylce index is assumed to be 10 but this can be
+  reset with the `-ec` option. The numbers of digits needed to pad the cycle
+  index and processor rank can also be overridden if necessary.
+
+**Magnetic Field:** The magnetic field is assumed to be zero unless a
+  VisItDataCollection is provided. The command line option `-br` can be used
+  to set the root name of the data collection e.g. `-br Tesla-AMR-Parallel`.
+  The field name within the data collection is assumed to be `B` unless
+  overridden with `-bf`. The cylce index is assumed to be 10 but this can be
+  reset with the `-bc` option. The numbers of digits needed to pad the cycle
+  index and processor rank can also be overridden if necessary.
+
+**Initial Position:** The initial position can be set with `-x0` e.g.
+  `-x0 '0.1 0.2 0.3'`. The default position is the center of the intersection
+  of the bounding boxes for the electric and magnetic field meshes.
+
+**Initial Momentum:** The initial momentum can be set with `-p0` e.g.
+  `-p0 '1 0 0'`. The default initial momentum is zero.
+
+**Other parameters:** A handful of other parameters can be adjusted from the
+  command line. The most useful of these would be the time step and final time
+  which can be reset with `-dt` and `tf` respectively.
+
+  The Lorentz mini application can create a "mesh" of the trajectory which
+  can be displayed using GLVis and/or VisIt. The mesh is made up of
+  quadrilateral elements forming a ribbon along the trajectory. One edge of
+  these quadrilaterals is aligned with the sequence of calculated positions.
+  The adjacent edges are related to the acceleration of the particle i.e.
+  $(\vec{p}\_{k} - \vec{p}\_{k-1})/(m \Delta t)$. To compute the edge length
+  this acceleration is scaled by a user defined quantity (the `-rf` command
+  line option can be used to adust this "ribbon" factor).
+
 <script type="text/x-mathjax-config">MathJax.Hub.Config({TeX: {equationNumbers: {autoNumber: "all"}}, tex2jax: {inlineMath: [['$','$']]}});</script>
 <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-AMS_HTML"></script>

src/examples.md

@@ -52,6 +52,7 @@ or post [questions](https://github.com/mfem/mfem/issues/new?labels=question) or
       <option id="nonlocal">Nonlocal</option>
       <option id="stochastic">Stochastic</option>
       <option id="freeboundary">Free boundary</option>
+      <option id="pic">Particle-In-Cell</option>
    </select>
 </div>
 <div class="col-sm-6 col-md-3 small" markdown="1">
@@ -1510,6 +1511,39 @@ moving to the miniapps.**_
 <br></div>
 
 
+<div id="lorentz" markdown="1">
+## Lorentz Miniapp: Particle Trajectory Calculation
+<img class="floatright" src="../img/examples/lorentz.png">
+
+This miniapp reads VisItDataCollection objects produced by applications such as
+Volta and Tesla (described above) and computes particle trajectories subject
+to the electric and magnetic fields described therein.
+
+This code uses the Boris algorithm to approximate the Lorentz force,
+
+$$\frac{d\vec{p}}{dt} = q \left(\vec{E} + \vec{v}\times\vec{B}\right),$$
+
+exerted on a test particle with a given mass, charge, initial position and
+momentum.
+
+The Lorentz miniapp musts be run on the same number of processors as the
+applications which produced the VisItDataCollection objects. However, the
+electric and magnetic fields do not need to be defined on the same mesh. The
+Lorentz miniapp relies on the `FindPoints` functionality available through
+MFEM's parallel mesh classes to query the field values even when those field
+values are located on different processors.
+
+For more details, please see the [documentation](electromagnetics.md) in the
+`miniapps/electromagnetics` directory.
+
+_The miniapp has only a parallel
+([lorentz.cpp](https://github.com/mfem/mfem/blob/master/miniapps/electromagnetics/lorentz.cpp)) version.
+**We recommend that new users start with the example codes before
+moving to the miniapps.**_
+<div style="clear:both;"/></div>
+<br></div>
+
+
 <div id="mobius-strip" markdown="1">
 ##Mobius Strip Miniapp
 <a href="https://glvis.org/live/?stream=../data/streams/mobius-strip.saved" target="_blank">
@@ -2446,17 +2480,18 @@ function update()
    + showElement("ex40", darcy && (l2 || hdiv) && (galerkin || mixed) && (gmres || newton))
 
    // nurbs miniapps
-   + showElement("nurbs_ex1", diffusion && nurbs && h1)
-   + showElement("nurbs_ex3", maxwell && nurbs && hcurl)
-   + showElement("nurbs_ex5", darcy && nurbs && hdiv)
-   + showElement("nurbs_ex11", diffusion && nurbs)
-   + showElement("nurbs_ex24", nurbs && (hcurl || hdiv))
+   + showElement("nurbs_ex1", diffusion && h1 && nurbs && all4)
+   + showElement("nurbs_ex3", maxwell && hcurl && nurbs && all4)
+   + showElement("nurbs_ex5", darcy && hdiv && nurbs && all4)
+   + showElement("nurbs_ex11", diffusion && all2 && nurbs && all4)
+   + showElement("nurbs_ex24", all1 && (hcurl || hdiv) && nurbs && all4)
 
    // electromagnetic miniapps
    + showElement("volta", maxwell && (l2 || hdiv) && (galerkin || amr) && (pcg || amg))
    + showElement("tesla", maxwell && (hdiv || hcurl) && (galerkin || amr) && (pcg || amg || ams))
    + showElement("maxwell", (maxwell || conduction || wave) && (hdiv || hcurl) && (galerkin || staticcond || mixed) && (pcg || symplectic))
    + showElement("joule", (maxwell || conduction) && (l2 || h1 || hdiv || hcurl) && (galerkin || amr || staticcond) && (pcg || amg || ams || ads || sdirk))
+   + showElement("lorentz", (maxwell || pic) && all2 && all3 && all4)
 
    // meshing miniapps
    + showElement("mobius-strip", meshing && all2 && all3 && all4)

src/features.md

@@ -131,6 +131,7 @@ Beyond the examples, a number of miniapps are available that are more representa
  - [Tesla](https://docs.mfem.org/html/tesla_8cpp_source.html): simple magnetostatics simulation code,
  - [Maxwell](https://docs.mfem.org/html/electromagnetics_2maxwell_8cpp_source.html): transient electromagnetics simulation code,
  - [Joule](https://docs.mfem.org/html/joule_8cpp_source.html): transient magnetics and Joule heating miniapp,
+ - [Lorentz](https://docs.mfem.org/html/lorentz_8cpp_source.html): particle trajectory calculation miniapp,
  - [Navier](https://docs.mfem.org/html/classmfem_1_1navier_1_1NavierSolver.html#details): solver for the incompressible time-dependent Navier-Stokes equations,
  - [Mesh Explorer](https://docs.mfem.org/html/mesh-explorer_8cpp_source.html): visualize and manipulate meshes,
  - [Mesh Optimizer](https://docs.mfem.org/html/mesh-optimizer_8cpp_source.html): optimize high-order meshes,