Docs: New Kin Energy APIs

ax3l · Oct 20, 2023 · dd3e139 · dd3e139
1 parent d0cd13a
commit dd3e139
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 9 deletions.
diff --git a/docs/source/usage/parameters.rst b/docs/source/usage/parameters.rst
@@ -53,6 +53,9 @@ Overall simulation parameters
 Setting up the field mesh
 -------------------------
 
+ImpactX uses an AMReX grid of boxes to organize and parallelize the simulation domain.
+These boxes also contain a field mesh, if space charge calculations are enabled.
+
 * ``amr.n_cell`` (3 integers) optional (default: 1 `blocking_factor <https://amrex-codes.github.io/amrex/docs_html/GridCreation.html>`__ per MPI process)
     The number of grid points along each direction (on the **coarsest level**)
 
@@ -114,7 +117,22 @@ Domain Boundary Conditions
 Initial Beam Distributions
 --------------------------
 
-* ``<distribution>.type`` (``string``)
+* ``beam.npart`` (``integer``)
+  number of weighted simulation particles
+
+* ``beam.units`` (``string``)
+  currently, only ``static`` is supported.
+
+* ``beam.kin_energy`` (``float``, in MeV)
+  beam kinetic energy
+
+* ``beam.charge`` (``float``, in C)
+  bunch charge
+
+* ``beam.particle`` (``string``)
+  particle type: currently either ``electron``, ``positron`` or ``proton``
+
+* ``beam.distribution`` (``string``)
     Indicates the initial distribution type.
     This should be one of:
 

diff --git a/docs/source/usage/python.rst b/docs/source/usage/python.rst
@@ -304,27 +304,27 @@ Particles
 
    .. py:property:: px
 
-      momentum in x, normalized to proper velocity
+      momentum in x, normalized to mass*c :math:`p_x = \gamma \beta_x`
 
    .. py:property:: py
 
-      momentum in y, normalized to proper velocity
+      momentum in y, normalized to mass*c :math:`p_x = \gamma \beta_x`
 
    .. py:property:: pz
 
-      momentum in z, normalized to proper velocity
+      momentum in z, normalized to mass*c :math:`p_x = \gamma \beta_x`
 
    .. py:property:: pt
 
-      energy deviation, normalized by rest energy
+      energy, normalized by rest energy :math:`p_t = -\gamma`
 
    .. py:property:: gamma
 
-      Read-only: Get reference particle relativistic gamma.
+      Read-only: Get reference particle relativistic gamma :math:`\gamma = 1/\sqrt{1-\beta^2}`
 
    .. py:property:: beta
 
-      Read-only: Get reference particle relativistic beta.
+      Read-only: Get reference particle relativistic beta :math:`\beta = v/c`
 
    .. py:property:: beta_gamma
 
@@ -342,9 +342,9 @@ Particles
 
       Write-only: Set reference particle rest mass (MeV/c^2).
 
-   .. py:method:: set_energy_MeV(energy_MeV)
+   .. py:method:: set_kin_energy_MeV(kin_energy_MeV)
 
-      Write-only: Set reference particle kinetic energy.
+      Write-only: Set reference particle kinetic energy (MeV)
 
    .. py:method:: load_file(madx_file)