From 10015d0a776d99a43d5a60158e7bfee2b84c7acf Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Fri, 20 Oct 2023 10:12:28 -0700 Subject: [PATCH] Docs: New Kin Energy APIs --- docs/source/usage/parameters.rst | 146 +++++++++++++++++-------------- docs/source/usage/python.rst | 16 ++-- 2 files changed, 90 insertions(+), 72 deletions(-) diff --git a/docs/source/usage/parameters.rst b/docs/source/usage/parameters.rst index d22bb3e11..77d438d71 100644 --- 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 `__ per MPI process) The number of grid points along each direction (on the **coarsest level**) @@ -114,104 +117,119 @@ Domain Boundary Conditions Initial Beam Distributions -------------------------- -* ``.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: * ``waterbag`` for initial Waterbag distribution. With additional parameters: - * ``.sigmaX`` (``float``, in meters) rms X - * ``.sigmaY`` (``float``, in meters) rms Y - * ``.sigmaT`` (``float``, in radian) rms normalized time difference T - * ``.sigmaPx`` (``float``, in momentum) rms Px - * ``.sigmaPy`` (``float``, in momentum) rms Py - * ``.sigmaPt`` (``float``, in energy deviation) rms Pt - * ``.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px - * ``.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py - * ``.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt + * ``beam.sigmaX`` (``float``, in meters) rms X + * ``beam.sigmaY`` (``float``, in meters) rms Y + * ``beam.sigmaT`` (``float``, in radian) rms normalized time difference T + * ``beam.sigmaPx`` (``float``, in momentum) rms Px + * ``beam.sigmaPy`` (``float``, in momentum) rms Py + * ``beam.sigmaPt`` (``float``, in energy deviation) rms Pt + * ``beam.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px + * ``beam.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py + * ``beam.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt * ``kurth6d`` for initial 6D Kurth distribution. With additional parameters: - * ``.sigmaX`` (``float``, in meters) rms X - * ``.sigmaY`` (``float``, in meters) rms Y - * ``.sigmaT`` (``float``, in radian) rms normalized time difference T - * ``.sigmaPx`` (``float``, in momentum) rms Px - * ``.sigmaPy`` (``float``, in momentum) rms Py - * ``.sigmaPt`` (``float``, in energy deviation) rms Pt - * ``.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px - * ``.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py - * ``.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt + * ``beam.sigmaX`` (``float``, in meters) rms X + * ``beam.sigmaY`` (``float``, in meters) rms Y + * ``beam.sigmaT`` (``float``, in radian) rms normalized time difference T + * ``beam.sigmaPx`` (``float``, in momentum) rms Px + * ``beam.sigmaPy`` (``float``, in momentum) rms Py + * ``beam.sigmaPt`` (``float``, in energy deviation) rms Pt + * ``beam.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px + * ``beam.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py + * ``beam.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt * ``gaussian`` for initial 6D Gaussian (normal) distribution. With additional parameters: - * ``.sigmaX`` (``float``, in meters) rms X - * ``.sigmaY`` (``float``, in meters) rms Y - * ``.sigmaT`` (``float``, in radian) rms normalized time difference T - * ``.sigmaPx`` (``float``, in momentum) rms Px - * ``.sigmaPy`` (``float``, in momentum) rms Py - * ``.sigmaPt`` (``float``, in energy deviation) rms Pt - * ``.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px - * ``.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py - * ``.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt + * ``beam.sigmaX`` (``float``, in meters) rms X + * ``beam.sigmaY`` (``float``, in meters) rms Y + * ``beam.sigmaT`` (``float``, in radian) rms normalized time difference T + * ``beam.sigmaPx`` (``float``, in momentum) rms Px + * ``beam.sigmaPy`` (``float``, in momentum) rms Py + * ``beam.sigmaPt`` (``float``, in energy deviation) rms Pt + * ``beam.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px + * ``beam.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py + * ``beam.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt * ``kvdist`` for initial K-V distribution in the transverse plane. The distribution is uniform in t and Gaussian in pt. With additional parameters: - * ``.sigmaX`` (``float``, in meters) rms X - * ``.sigmaY`` (``float``, in meters) rms Y - * ``.sigmaT`` (``float``, in radian) rms normalized time difference T - * ``.sigmaPx`` (``float``, in momentum) rms Px - * ``.sigmaPy`` (``float``, in momentum) rms Py - * ``.sigmaPt`` (``float``, in energy deviation) rms Pt - * ``.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px - * ``.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py - * ``.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt + * ``beam.sigmaX`` (``float``, in meters) rms X + * ``beam.sigmaY`` (``float``, in meters) rms Y + * ``beam.sigmaT`` (``float``, in radian) rms normalized time difference T + * ``beam.sigmaPx`` (``float``, in momentum) rms Px + * ``beam.sigmaPy`` (``float``, in momentum) rms Py + * ``beam.sigmaPt`` (``float``, in energy deviation) rms Pt + * ``beam.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px + * ``beam.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py + * ``beam.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt * ``kurth4d`` for initial 4D Kurth distribution in the transverse plane. The distribution is uniform in t and Gaussian in pt. With additional parameters: - * ``.sigmaX`` (``float``, in meters) rms X - * ``.sigmaY`` (``float``, in meters) rms Y - * ``.sigmaT`` (``float``, in radian) rms normalized time difference T - * ``.sigmaPx`` (``float``, in momentum) rms Px - * ``.sigmaPy`` (``float``, in momentum) rms Py - * ``.sigmaPt`` (``float``, in energy deviation) rms Pt - * ``.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px - * ``.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py - * ``.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt + * ``beam.sigmaX`` (``float``, in meters) rms X + * ``beam.sigmaY`` (``float``, in meters) rms Y + * ``beam.sigmaT`` (``float``, in radian) rms normalized time difference T + * ``beam.sigmaPx`` (``float``, in momentum) rms Px + * ``beam.sigmaPy`` (``float``, in momentum) rms Py + * ``beam.sigmaPt`` (``float``, in energy deviation) rms Pt + * ``beam.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px + * ``beam.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py + * ``beam.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt * ``semigaussian`` for initial Semi-Gaussian distribution. The distribution is uniform within a cylinder in (x,y,z) and Gaussian in momenta (px,py,pt). With additional parameters: - * ``.sigmaX`` (``float``, in meters) rms X - * ``.sigmaY`` (``float``, in meters) rms Y - * ``.sigmaT`` (``float``, in radian) rms normalized time difference T - * ``.sigmaPx`` (``float``, in momentum) rms Px - * ``.sigmaPy`` (``float``, in momentum) rms Py - * ``.sigmaPt`` (``float``, in energy deviation) rms Pt - * ``.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px - * ``.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py - * ``.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt + * ``beam.sigmaX`` (``float``, in meters) rms X + * ``beam.sigmaY`` (``float``, in meters) rms Y + * ``beam.sigmaT`` (``float``, in radian) rms normalized time difference T + * ``beam.sigmaPx`` (``float``, in momentum) rms Px + * ``beam.sigmaPy`` (``float``, in momentum) rms Py + * ``beam.sigmaPt`` (``float``, in energy deviation) rms Pt + * ``beam.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px + * ``beam.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py + * ``beam.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt * ``triangle`` a triangle distribution for laser-plasma acceleration related applications. A ramped, triangular current profile with a Gaussian energy spread (possibly correlated). The transverse distribution is a 4D waterbag. With additional parameters: - * ``.sigmaX`` (``float``, in meters) rms X - * ``.sigmaY`` (``float``, in meters) rms Y - * ``.sigmaT`` (``float``, in radian) rms normalized time difference T - * ``.sigmaPx`` (``float``, in momentum) rms Px - * ``.sigmaPy`` (``float``, in momentum) rms Py - * ``.sigmaPt`` (``float``, in energy deviation) rms Pt - * ``.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px - * ``.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py - * ``.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt + * ``beam.sigmaX`` (``float``, in meters) rms X + * ``beam.sigmaY`` (``float``, in meters) rms Y + * ``beam.sigmaT`` (``float``, in radian) rms normalized time difference T + * ``beam.sigmaPx`` (``float``, in momentum) rms Px + * ``beam.sigmaPy`` (``float``, in momentum) rms Py + * ``beam.sigmaPt`` (``float``, in energy deviation) rms Pt + * ``beam.muxpx`` (``float``, dimensionless, default: ``0``) correlation X-Px + * ``beam.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py + * ``beam.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt .. _running-cpp-parameters-lattice: diff --git a/docs/source/usage/python.rst b/docs/source/usage/python.rst index 88832378e..2eb145e40 100644 --- 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)