Lattice Properties
==================

General parameter
-----------------

Basic format of the general parameters are,

.. code-block:: none

    keyword1 = "value1";
    keyword2 = "value2";
    ...

.. _genpara:

.. list-table::
    :header-rows: 1
    :widths: 2, 2, 6

    * - | keyword
      - | value
      - | description
    * - | **sim_type**
      - | "MomentMatrix"
      - | Simulation mode. FRIB simulation uses
        | the particular mode "MomentMatrix".
    * - | **MpoleLevel**
      - | "0", "1", or "2"
      - | Multipole term controller for the rf cavities.
        | "0" - only include focusing and defocusing effect
        | "1" - include dipole terms
        | "2" - include dipole and quadrupole terms
    * - | **EmitGrowth**
      - | "0" or "1"
      - | Flag for cross-cavity emittance growth effect.
        | "0" - False (no emittance growth)
        | "1" - True (calculate emittance growth)
    * - | **HdipoleFitMode**
      - | "0" or "1"
      - | Flag for auto-adjustment of bending element
        | "0" - use "bg" or "beta" for the bending strength
        | "1" - auto-adjust the bending strength

Beam parameter
--------------

Basic format of the beam parameters are,

.. code-block:: none

    keyword1 = value1;
    keyword2 = [value2, value3]; # list input
    ...

.. _beampara:

.. list-table::
    :header-rows: 1
    :widths: 3, 2 , 6

    * - | keyword
      - | value
      - | description
    * - | **IonEs**
      - | float
      - | Nucleaon mass of the reference beam. [eV/u]
    * - | **IonEk**
      - | float
      - | Initial kinetic energy of the reference beam. [eV/u]
    * - | **SampleFreq**
      - | float
      - | Sampling frequency. [Hz] (default is 80.5e6 [Hz])
    * - | **IonChargeStates**
      - | list of float
      - | List of charge to mass ratios of the all charge states. [1]
        | The first element is used as the reference beam.
    * - | **NCharge**
      - | list of float
      - | List of macro weights of the all charge states. [1]
    * - | **${vector_variable}${n}**
      - | vector[7]
      - | Initial centroid vector of the **n**-th charge state.
        | *${vector_variable}* is defined in :cpp:type:`source`.
        | :math:`[x, x', y, y', \phi, E_k, 1]` with
        | [mm, rad, mm, rad, rad, MeV/u, 1]
    * - | **${matrix_variable}${n}**
      - | vector[49]
      - | Flattened initial envelope matrix of the **n**-th charge state.
        | *${matrix_variable}* is defined in :cpp:type:`source`.
        | Cartisan product of :math:`[x, x', y, y', \phi, E_k, 1]^2` with
        | [mm, rad, mm, rad, rad, MeV/u, 1] :math:`^2`
    * - | **Eng_Data_Dir**
      - | string
      - | Directory path of the rf cavity data.
        | ``dir(path)`` supports relative path.


.. _element:

Lattice elements
----------------

Basic format of the one lattice element is,

.. code-block:: none

    name_of_element1: element_type, parameter1 = value1, parameter2 = value2, ... ;

After writing down the all lattice elements, user need to specify the lattice cell and the cell to USE.

.. code-block:: none

    # define the cell
    name_of_cell: LINE = ( name_of_element1, name_of_element2, name_of_element3, ... );

    # set the cell to USE
    USE: name_of_cell;

.. list-table::
    :header-rows: 1
    :widths: 3 , 6

    * - **element_type**
      - description
    * - :cpp:type:`source`
      - Starting point of the simulation.
    * - :cpp:type:`marker`
      - Marker element.
    * - :cpp:type:`stripper`
      - Chage stripper element.
    * - :cpp:type:`tmatrix`
      - User input transfer matrix.
    * - :cpp:type:`orbtrim`
      - Orbit trim element.
    * - :cpp:type:`drift`
      - Drift space element.
    * - :cpp:type:`solenoid`
      - Solenoid magnet element.
    * - :cpp:type:`quadrupole`
      - Magnetic quadrupole element.
    * - :cpp:type:`sextupole`
      - Magnetic sextupole element.
    * - :cpp:type:`equad`
      - Electrostatic quadrupole element.
    * - :cpp:type:`sbend`
      - Magnetic bend element.
    * - :cpp:type:`edipole`
      - Electrostatic dipole element.
    * - :cpp:type:`rfcavity`
      - RF cavity element.

Special element
^^^^^^^^^^^^^^^

.. cpp:type:: source

    Starting point of the simulation. Initial beam state parameters are set at this element.

    :parameters: **vector_variable**: string

                    | Name key of the initial centroid vector.

                 **matrix_variable**: string

                    | Name key of the initial envelope matrix.

.. cpp:type:: marker

    Marker element. Nothing to do.

.. cpp:type:: stripper

    Stripper element.

    :parameters: **IonChargeStates**: list of float

                    | List of charge to mass ratios after the charge stripper. [1]

                 **charge_model**: string

                    | Macro weight model for stripper.
                    | - **"baron" (default)**: Use Baron formula for the macro weights.
                    | - **"off"**: Use ``NCharge`` parameter for the macro weights.

                 **NCharge**: list of float

                    | List of macro weights after the charge stripper. [1]
                    | This list length must be same as the ``IonChargeStates``
                    | This parameter is used only in the case of ``charge_model = "baron"``.

                 **Stripper_IonZ**: float (optional, default is **78.0/238.0**)

                    | Charge to mass ratio of the reference beam. [1]

                 **Stripper_IonMass**: float (optional, default is **238.0**)

                    | Ion mass of the reference beam. [amu]

                 **Stripper_IonProton**: float (optional, default is **92.0**)

                    | Proton number of the reference beam. [1]

                 **Stripper_E1Para**: float (optional, default is **2.8874e-3**)

                    | Constant part of the energy struggling parameter of the charge stripper. [MeV/u]

                 **Stripper_lambda**: float (optional, default is **5.5740**)

                    | Momentum spread factor :math:`\lambda` of the charge stripper. [1]

                 **Stripper_upara**: float (optional, default is **2.6903**)

                    | Momentum spread factor :math:`U` of the charge stripper. [1]
                    | The momentum spread is defined as :math:`\sqrt(U/\lambda^2)` [mrad].

                 **Stripper_E0Para**: vector[3] (optional, default is **[16.348e6, 1.00547, -0.10681]**)

                    | Energy loss parameters due to the ionization.
                    | [Constant_part, Energy_dependence, Thickness_depenedence] with [eV/u, 1, 1]

                 **Stripper_Para**: vector[3] (optional, default is **[3.0, 20.0, 16.623e6]**)

                    | Stripper foil parameters.
                    | [Thickness, Thickness_variation, reference_energy] with [um, %, eV/u]

.. cpp:type:: tmatrix

    User input transfer matrix element.

    :parameter: **matrix**: vector[49]

                    | Flattened :math:`7 \times 7` transfer matrix.


Optical element
^^^^^^^^^^^^^^^

.. cpp:type:: orbtrim

    Orbit trim element. This can be use as steering magnet.

    :parameters: **realpara**: int

                    | Realistic input parameter flag for the beam kick angle.
                    | **0** - use ``theta_x`` and ``theta_y`` for the beam kick.
                    | **1** - use ``tm_xkick`` and ``tm_ykick`` for the beam kick.

                 **theta_x**: float

                    | Horizontal beam kick angle. [rad]

                 **theta_y**: float

                    | Vertical beam kick angle. [rad]

                 **tm_xkick**: float

                    | Magnetic field strength for the horizontal beam kick. [T*m]


                 **tm_ykick**: float

                    | Magnetic field strength for the vertical beam kick. [T*m]

                 **xyrotate**: float

                    | Transverse rotation angle of the beam. [deg]

    .. Note::

        In the case of user puts both "beam kick information" and "transverse rotation angle" to the ONE orbtrim element,
        the process order is, transverse rotation -> beam kick. In other words, the beam kick is effected AFTER the transverse rotation.

.. cpp:type:: drift

    Drift space element.

    :parameters: **L**: float

                    | Length of the lattice element. [m]

.. cpp:type:: solenoid

    Solenoid magnet element.

    :parameters: **L**: float

                    | Length of the lattice element. [m]

                 **B**: float

                    | Solenoid strength (:math:`B_z`). [T]

                 **dx**: float (default: 0.0)

                    | Misalignment of horizontal shift. [m]

                 **dy**: float (default: 0.0)

                    | Misalignment of vertical shift. [m]

                 **pitch**: float (default: 0.0)

                    | Misaglignment of pitch angle. [rad]

                 **yaw**: float (default: 0.0)

                    | Misaglignment of yaw angle. [rad]

                 **roll**: float (default: 0.0)

                    | Misaglignment of roll angle. [rad]

                 **ncurve**: int (default: 0)

                    | Number of curves for slanted and overlapped field.
                    | (0 means hard-edge fringe model)

                 **scl_fac${n}**: float (default: 0)

                    | Scaling factor of the *n*-th curve (*n* start from 0).
                    | Unit of scl_fac${n}\*curve${n} is [T].

                 **curve${n}**: vector

                    | *n*-th Curve information (*n* start from 0).
                    | Each curve vector must have the same size.
                      The vector elements should be defined by the scaled strength of the element at the step.
                      Also, the step size is defined by "**L** divided by the size of **curve${n}**".

                 **CurveFile**: string

                    | External file name for the curves, the file format is the same as **curve${n}**.
                    | e.g. `curve0 = [1.0, 2.0, ...];`
                    | If CurveFile is available, it overrides the **curve${n}**.

                 **use_range**: vector[2]

                    | Use range of **curve${n}**. Format is [start_id, end_id].

.. cpp:type:: quadrupole

    Magnetic quadrupole element.

    :parameters: **L**: float

                    | Length of the lattice element. [m]

                 **B2**: float

                    | Quadrupole field gradient. [T/m]
                    | Positive value means horizontal focusing.

                 **dx**, **dy**, **pitch**, **yaw**, **roll**: float

                    | Misalignment parameters. See :cpp:type:`solenoid` case.

                 **ncurve**, **scl_fac${n}**, **curve${n}**, **CurveFile**, **use_range**

                    | Curve inputs for slanted and overlapped field. See :cpp:type:`solenoid` case.
                    | Unit of scl_fac${n}\*curve${n} is [T/m].

.. cpp:type:: sextupole

    Magnetic sextupole element.

    :parameters: **L**: float

                    | Length of the lattice element. [m]

                 **B3**: float

                    | Sextupole field gradient. [T/m^2]
                    | Positive value means horizontal focusing.

                 **dstkick**: bool

                    | On/off flag to calculate the centroid shift due to the 3rd order effect.
                    | Default is **1** (on).

                 **step**: int

                    | Step number for the sextupole element. Default is **1**.

                 **dx**, **dy**, **pitch**, **yaw**, **roll**: float

                    | Misalignment parameters. See :cpp:type:`solenoid` case.

.. cpp:type:: equad

    Electrostatic quadrupole element.

    :parameters: **L**: float

                    | Length of the lattice element. [m]

                 **V**: float

                    | Electrostatic quadrupole pole tip voltage. [V]
                    | Positive value means horizontal focusing.

                 **radius**: float

                    | Electrostatic quadrupole pole tip radius. [m]

                 **dx**, **dy**, **pitch**, **yaw**, **roll**: float

                    | Misalignment parameters. See :cpp:type:`solenoid` case.

                 **ncurve**, **scl_fac${n}**, **curve${n}**, **CurveFile**, **use_range**

                    | Curve inputs for slanted and overlapped field. See :cpp:type:`solenoid` case.
                    | Unit of scl_fac${n}\*curve${n} is [V/m^2].

.. cpp:type:: sbend

    Magnetic bend (dipole) element.

    :parameters: **L**: float

                    | Length of the lattice element. [m]

                 **phi**: float

                    | Bend angle. [deg]

                 **phi1**: float

                    | Front pole face angle. [deg]

                 **phi2**: float

                    | Back pole face angle. [deg]

                 **bg**: float (optional: Used in the case of :ref:`"HdipoleFitMode" <genpara>` is **0**.)

                    | Lorentz :math:`\beta \gamma` for the reference beam. [1]
                    | This parameter is correspond to the bend field strength.

                 **dx**, **dy**, **pitch**, **yaw**, **roll**: float

                    | Misalignment parameters. See :cpp:type:`solenoid` case.

.. cpp:type:: edipole

    Electrostatic dipole (bend) element.

    :parameters: **L**: float

                    | Length of the lattice element. [m]

                 **phi**: float

                    | Bend angle. [deg]

                 **beta**: float (optional: Used in the case of :ref:`"HdipoleFitMode" <genpara>` is **0**.)

                    | Lorentz :math:`\beta` for the reference beam. [1]
                    | This parameter is correspond to the bend field strength.

                 **fringe_x**: float

                    | Horizontal fringe term. [rad/mm]

                 **fringe_y**: float

                    | Vertical fringe term. [rad/mm]

                 **asymfac**: float

                    | Characteristic parameter of the kinetic energy change
                      due to the middle point potential deviation from ground. [1]

                 **spher**: int

                    | Flag for the electrostatic dipole shape.
                    | **0** - cylindrical electrostatic dipole
                    | **1** - spherical electrostatic dipole

                 **ver**: int

                    | Flag for the bending direction.
                    | **0** - horizontal bend
                    | **1** - vertical bend

                 **dx**, **dy**, **pitch**, **yaw**, **roll**: float

                    | Misalignment parameters. See :cpp:type:`solenoid` case.

.. cpp:type:: rfcavity

    RF cavity element.

    :parameters: **L**: float

                    | Length of the lattice element. [m]

                 **cavtype**: string

                    | Cavity type. Supports "Generic", "0.041QWR", "0.085QWR", "0.29HWR", and "0.53HWR".
                      :ref:`The file format is described here. <cavformat>`

                 **f**: float

                    | RF frequency of the cavity. [Hz]

                 **phi**: float

                    | Input phase of the cavity. [deg]

                 **syncflag**: int

                    | Flag for synchronous phase input (for above parameter **phi**).
                    |    **0** for driven phase input.
                    |    **1** for synchronous phase input with complex fit model. (default)
                    |    **2** for synchronous phase input with sinusoidal fit model.

                 **scl_fac**: float

                    | Scaling factor of the field. [1]

                 **datafile**: string (optional: Used in the case of ``cavtype`` = "Generic")

                    | File path of the rf cavity data.

                 **Rm**: float (optional: Used in the case of ``cavtype`` = "Generic")

                    | Characteristic radial length of the multipole expansion. [mm]

                 **dx**, **dy**, **pitch**, **yaw**, **roll**: float

                    | Misalignment parameters. See :cpp:type:`solenoid` case.


.. _cavformat:

Rf cavity data format
---------------------

FLAME using Thin-Lens-Model for rf cavity calculation.
Rf cavity data is composed of "Longitudinal axis data", "Multipole lattice data", "Multipole field data", and "TTF fitting data".

Hard-coded FRIB cavity models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For typical rf cavity in FRIB, the "TTF fitting data" is hard-coded in FLAME.
Following files are required for each rf cavity type.

.. list-table::
    :header-rows: 1

    * - **cavtype**
      - **Longitudinal axis data**
      - **Multipole lattice data**
      - **Multipole field data**
    * - "0.041QWR"
      - "axisData_41.txt"
      - "Multipole41/thinlenlon_41.txt"
      - "Multipole41/CaviMlp_41.txt"
    * - "0.085QWR"
      - "axisData_85.txt"
      - "Multipole85/thinlenlon_85.txt"
      - "Multipole85/CaviMlp_85.txt"
    * - "0.29HWR"
      - "axisData_29.txt"
      - "Multipole29/thinlenlon_29.txt"
      - "Multipole29/CaviMlp_29.txt"
    * - "0.53HWR"
      - "axisData_53.txt"
      - "Multipole53/thinlenlon_53.txt"
      - "Multipole53/CaviMlp_53.txt"

Generic rf cavity model
^^^^^^^^^^^^^^^^^^^^^^^

FLAME supports *lattice format* input for the generic rf cavity model.

The basic format of the rf cavity data is similar to the main lattice file,

.. code-block:: none

    Rm = value1;

    Ez = [
    z1, Ez1,
    z2, Ez2,
    z3, Ez3,
    ...
    ];

    name_of_element1: element_type, parameter1 = value1, parameter2 = value2, ... ;
    ...

    cell: LINE =(name_of_element1, ...);
    USE: cell;

.. list-table::
    :header-rows: 1
    :widths: 2, 2, 6

    * - | keyword
      - | value
      - | description
    * - | **Rm**
      - | float
      - | Characteristic radial length of the multipole expansion. [mm]
    * - | **Ez**
      - | vector[2*n]
      - | On axis :math:`E_z` data.
        | The odd index (1,3,5,...) is z position. [mm]
        | The even index (2,4,6,...) is Electric field strength. [V/m]
    * - | **RefNorm**
      - | float
      - | Reference normalization factor for complex synchronous phase definition.
        | This value is defined by :math:`q A/m` where :math:`A` is the scaling factor of the 3D EM field.
        | If **RefNorm** or **SyncFit** are not defined, sinusoidal model is used for the synchronous phase definition.
    * - | **SyncFit**
      - | vector[5*n]
      - | Fitting parameters for complex synchronous phase definition.
        | The fitting model is shown :ref:`here <ttfnote>`.
    * - | **EnergyLimit**
      - | vector[2]
      - | Lower and higher limit for incident energy. [MeV]
        | This value is used for warning signs only.
    * - | **NormLimit**
      - | vector[2]
      - | Lower and higher limit for normalization factor.
        | This value is used for warning signs only.

Lattice element for the rf cavity data
""""""""""""""""""""""""""""""""""""""""""

Drift space is the same format as the main lattice but unit of ``L`` is [mm] - :cpp:type:`drift`

.. cpp:type:: EDipole

    Dipole term generated by the electric field.

    :parameters: **L**: float

                    | Length of the lattice element. [mm]
                    | This parameter should be 0.0 in Thin-Lens-Model.

                 **V0**: float

                    | Amplitude of the multipole term. [MV]

                 **attr**: vector[20]

                    | TTF fitting parameter. :ref:`(see here) <ttfnote>`
                    | 1 to 10 - fitting parameter for :math:`T`
                    | 11 to 20 - fitting parameter for :math:`S`

.. cpp:type:: EFocus

    Constant focusing term generated by the electric field.

    Parameters are the same as :cpp:type:`EDipole`.

.. cpp:type:: EQuad

    Quadrupole term generated by the electric field.

    Parameters are the same as :cpp:type:`EDipole`.


.. cpp:type:: HMono

    Dipole term generated by the magnetic field.

    :parameters: **L**: float

                    | Length of the lattice element. [mm]
                    | This parameter should be 0.0 in Thin-Lens-Model.

                 **V0**: float

                    | Amplitude of the multipole term. [MA]

                 **attr**: vector[20]

                    | TTF fitting parameter. :ref:`(see here) <ttfnote>`
                    | 1 to 10 - fitting parameter for :math:`T`
                    | 11 to 20 - fitting parameter for :math:`S`

.. cpp:type:: HFocus

    Constant focusing term generated by the magnetic field.

    Parameters are the same as :cpp:type:`HMono`.

.. cpp:type:: HQuad

    Quadrupole term generated by the magnetic field.

    Parameters are the same as :cpp:type:`HMono`.

.. cpp:type:: AccGap

    Acceleration gap term by the longitudinal electric field.

    :parameters: **L**: float

            | Length of the lattice element. [mm]
            | This parameter should be 0.0 in Thin-Lens-Model.

         **V0**: float

            | Amplitude of the multipole term. [MV]

         **attr**: vector[23]

            | TTF fitting parameter. :ref:`(see here) <ttfnote>`
            | 1 to 10 - fitting parameter for :math:`T`
            | 11 to 20 - fitting parameter for :math:`S`
            | 21 to 23 - fitting parameter for the synchronous phase


.. _ttfnote:

.. Note::

    FLAME is using TTF-calculation acceleration technique to boost cavity modeling speed.
    TTF factor :math:`T` and :math:`S` are pre-calculated and fitted using 9th order polynomial function according
    to different particle phase speed :math:`k`. :math:`n`-th fitting parameter :math:`p_n` is listed as,

    .. math::

        T(k), S(k) = \sum^9_{n=0} p_n k^{(9-n)}.

    The driven-phase calculation is also boosted by using fitting model for the energy gain curve.

    For the sinusoidal fitting model, the phase transferring factor :math:`\varphi_c` is fitted by using

    .. math::

        \varphi_c = p_0 E^{p_1} + p_2.

    Here, :math:`E` is the kinetic energy and :math:`p_{i = 0, 1, 2}` are the fitting parameters.

    For other complex models (e.g. peak-base model), the phase transferring factor depends on the normalization factor :math:`g = q A/m` where :math:`A` is the scaling factor of the 3D EM field. The fitting model for :math:`\varphi_c` is,

    .. math::

        \varphi_c = \sum_{i=0}^n (p_{5i} E^{p_{5i+1}} + p_{5i+2} \ln(E) + p_{5i+3}e^E + p_{5i+4})\times g^i .

    Here, user can determine :math:`n` value corresponds to the size of **SyncFit**.

    The driven phase :math:`\varphi_d` is calculated by using :math:`\varphi_c`,

    .. math::

        \varphi_d = \varphi_s - \varphi_c - m \varphi_\text{abs}

    where, :math:`\varphi_s` is the synchronous phase in input, :math:`\varphi_\text{abs}`
    is absolute phase in front of the rf cavity, and :math:`m` is the harmonic number.