From ff8dec38c4f6759db03df4e44f169b5a52b4a152 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Fri, 14 Nov 2025 17:21:32 -0800 Subject: [PATCH 01/21] modified three files --- source/parameters/beambeam.md | 17 +++++++++++++++-- source/parameters/initialparticle.md | 23 ++++++++++++++++++++++- source/parameters/tracking.md | 10 ++++++++++ 3 files changed, 47 insertions(+), 3 deletions(-) diff --git a/source/parameters/beambeam.md b/source/parameters/beambeam.md index 3e70aad..b8c8695 100644 --- a/source/parameters/beambeam.md +++ b/source/parameters/beambeam.md @@ -1,5 +1,18 @@ (s:beambeam.params)= -## BeamBeamP: Beambeam Parameters +## BeamBeamP: BeamBeam Parameters -In Construction... +The `BeamBeamP` parameter group describes a particle beam element +from the opposite moving colliding beam. + +The inputs of `BeamBeamP` are: +```{code} yaml +BeamBeamP: + sigx # The horizontal beam size of the opposite beam (default: 0 m). + sigy # The vertical beam size of the opposite beam (default: 0 m). + xdisp # The horizontal displacement of the opposite beam (default: 0 m). + ydisp # The vertical displacement of the opposite beam (default: 0 m). + charge # The charge of the opposite beam (default: 1 for proton). + energy # The total energy in eV of the opposite beam. + Npart # Number of charged particles of the opposite beam. +``` diff --git a/source/parameters/initialparticle.md b/source/parameters/initialparticle.md index 7ebdcd1..87efb85 100644 --- a/source/parameters/initialparticle.md +++ b/source/parameters/initialparticle.md @@ -2,5 +2,26 @@ (s:init.particle.params)= ## InitialParticleP: Initial Particle Coordinates Parameters -In Construction... +The `InitialParticleP` parameter group contains parameters for describing the +initial beam particle distribution. +The components of this group are: +```{code} yaml +InitialParticleP: + Distype: "" # [string] name of initial distribution type + sigx # RMS x = sqrt() + sigpx # RMS px = sqrt() + muxpx # + xoff # + pxoff # + sigy # RMS y = sqrt() + sigpy # RMS py = sqrt() + yoff # + pyoff # + muypy # + sigz # RMS z = sqrt() + sigpz # RMS pz = sqrt() + muzpz # + zoff # + pzoff # +``` diff --git a/source/parameters/tracking.md b/source/parameters/tracking.md index 5a3f7cc..65af9e5 100644 --- a/source/parameters/tracking.md +++ b/source/parameters/tracking.md @@ -5,5 +5,15 @@ Tracking parameters are highly program specific but it is useful to have a group having some standardization. +The `TrackingP` parameter group contains parameters for describing the particle +tracking. +The components of this group are: +```{code} yaml +ReferenceP: + tracking_type: "" # [string] type of tracking + start_loc: "" # [string] Where tracking starts + end_loc: "" # [string] Where tracking ends + ... +``` In Construction... From 0fbf8407e601d91b35c2c72e68560f29d7f9a7ce Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Tue, 18 Nov 2025 11:26:28 -0800 Subject: [PATCH 02/21] modified 3 parameter files. --- source/parameters/beambeam.md | 7 +++++-- source/parameters/initialparticle.md | 2 +- source/parameters/tracking.md | 2 -- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/source/parameters/beambeam.md b/source/parameters/beambeam.md index b8c8695..0ff02d3 100644 --- a/source/parameters/beambeam.md +++ b/source/parameters/beambeam.md @@ -9,8 +9,11 @@ The inputs of `BeamBeamP` are: BeamBeamP: sigx # The horizontal beam size of the opposite beam (default: 0 m). sigy # The vertical beam size of the opposite beam (default: 0 m). - xdisp # The horizontal displacement of the opposite beam (default: 0 m). - ydisp # The vertical displacement of the opposite beam (default: 0 m). + sigz # The longitudinal beam size of the opposite beam (default: 0 m). + alpha_x # The horizontal Twiss parameter alpha at interaction point + beta_x # The horizontal Twiss parameter beta at interaction point + alpha_y # The vertical Twiss parameter alpha at interaction point + beta_y # The vertical Twiss parameter beta at interaction point charge # The charge of the opposite beam (default: 1 for proton). energy # The total energy in eV of the opposite beam. Npart # Number of charged particles of the opposite beam. diff --git a/source/parameters/initialparticle.md b/source/parameters/initialparticle.md index 87efb85..59cda66 100644 --- a/source/parameters/initialparticle.md +++ b/source/parameters/initialparticle.md @@ -7,7 +7,7 @@ initial beam particle distribution. The components of this group are: ```{code} yaml InitialParticleP: - Distype: "" # [string] name of initial distribution type + distribution_type: "" # [string] name of initial distribution type sigx # RMS x = sqrt() sigpx # RMS px = sqrt() muxpx # diff --git a/source/parameters/tracking.md b/source/parameters/tracking.md index 65af9e5..d4f93c9 100644 --- a/source/parameters/tracking.md +++ b/source/parameters/tracking.md @@ -11,8 +11,6 @@ The components of this group are: ```{code} yaml ReferenceP: tracking_type: "" # [string] type of tracking - start_loc: "" # [string] Where tracking starts - end_loc: "" # [string] Where tracking ends ... ``` In Construction... From efc87158bce8a49aacb075d89ff0bed79c8e16a4 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Wed, 19 Nov 2025 15:08:50 -0800 Subject: [PATCH 03/21] updated beambeam.md and element-kinds.md --- source/element-kinds.md | 41 +++++++++++++++++++++++++++-------- source/parameters/beambeam.md | 18 +++++++-------- 2 files changed, 41 insertions(+), 18 deletions(-) diff --git a/source/element-kinds.md b/source/element-kinds.md index b6f321a..5451e54 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -16,9 +16,8 @@ cleo: # [string] user-defined name (s:ackicker)= ## ACKicker Element -Time varying kicker element - -Under Construction... +An ACKicker element simulates a time-dependent kicker. +It is like a Kicker element except that the field varies in time. Element parameter groups associated with this element kind are: - [**ACKickerP**](#s:ackicker.params): AC kicker parameters. @@ -30,13 +29,22 @@ Element parameter groups associated with this element kind are: - [**ReferenceChangeP**](#s:ref.change.params): Reference energy change and/or reference time correction. - [**TrackingP**](#s:tracking.params): Tracking parameters. +Example: +```{code} yaml +ack1: + kind: ACKicker + length: 0.3 + t_offset: 0.1e-8 + scale_multipoles: = F + b1: = 0.27 + amplitude_vs_time: = {(-1.2e-6, 0.02), ... } + %--------------------------------------------------------------------------------------------------- (s:beambeam)= ## BeamBeam Element Element for simulating colliding beams. - -Under Construction... +A BeamBeam element defines the parameters of a oppositely moving "strong" beam that generates electromagnetic fields at the interaction point. This strong beam is assumed to have a three-dimensional (3D) Gaussian density distribution. Element parameter groups associated with this element kind are: - [**ApertureP**](#s:aperture.params): Aperture parameters. @@ -48,7 +56,15 @@ Element parameter groups associated with this element kind are: - [**ReferenceChangeP**](#s:ref.change.params): Reference energy change and/or reference time correction. - [**TrackingP**](#s:tracking.params): Tracking parameters. -The length of this element is considered to be zero so if `length` is specified, it must be zero. +Example: +```{code} yaml +bb1: + kind: BeamBeam + sigma_x: 0.1e-3 + sigma_y: 0.1e-3 + sigma_z: 5.0e-2 + energy: 1.0e10 + N_particle: 1.0e11 %--------------------------------------------------------------------------------------------------- (s:beginningele)= @@ -126,9 +142,8 @@ The length of this element is considered to be zero so if `length` is specified, (s:crabcavity)= ## CrabCavity Element -RF crab cavity - -Under Construction... +A CrabCavity element is an zero length RF cavity that gives a longitudinal dependent +transverse kick. Element parameter groups associated with this element kind are: - [**ApertureP**](#s:aperture.params): Aperture parameters. @@ -141,6 +156,14 @@ Element parameter groups associated with this element kind are: - [**ReferenceChangeP**](#s:ref.change.params): Reference energy change and/or reference time correction. - [**TrackingP**](#s:tracking.params): Tracking parameters. +Example: +```{code} yaml +cc1: + kind: CrabCavity + frequency: 394.0e6 + phase: 0.0 + voltage: 1.0e6 + %--------------------------------------------------------------------------------------------------- (s:drift)= ## Drift Element diff --git a/source/parameters/beambeam.md b/source/parameters/beambeam.md index 0ff02d3..bea8a37 100644 --- a/source/parameters/beambeam.md +++ b/source/parameters/beambeam.md @@ -7,15 +7,15 @@ from the opposite moving colliding beam. The inputs of `BeamBeamP` are: ```{code} yaml BeamBeamP: - sigx # The horizontal beam size of the opposite beam (default: 0 m). - sigy # The vertical beam size of the opposite beam (default: 0 m). - sigz # The longitudinal beam size of the opposite beam (default: 0 m). - alpha_x # The horizontal Twiss parameter alpha at interaction point - beta_x # The horizontal Twiss parameter beta at interaction point - alpha_y # The vertical Twiss parameter alpha at interaction point - beta_y # The vertical Twiss parameter beta at interaction point + sigma_x # The horizontal beam size of the opposite beam (default: 1 mm). + sigma_y # The vertical beam size of the opposite beam (default: 1 mm). + sigma_z # The longitudinal beam size of the opposite beam (default: 0 m). + alpha_x # The horizontal Twiss parameter alpha at interaction point (default: 0). + beta_x # The horizontal Twiss parameter beta at interaction point (default 1 m). + alpha_y # The vertical Twiss parameter alpha at interaction point (default 0 m). + beta_y # The vertical Twiss parameter beta at interaction point (default 1 m). charge # The charge of the opposite beam (default: 1 for proton). - energy # The total energy in eV of the opposite beam. - Npart # Number of charged particles of the opposite beam. + energy # The total energy in eV of the opposite beam (default: 1e12. + N_particle # Number of particles in the opposite beam (default: 0). ``` From fb798132c8363ed06c23b258a1f6d097b1c588d0 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Wed, 19 Nov 2025 17:02:20 -0800 Subject: [PATCH 04/21] added description of elements in the element-kinds.md --- source/element-kinds.md | 58 +++++++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 19 deletions(-) diff --git a/source/element-kinds.md b/source/element-kinds.md index 5451e54..7fd99ee 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -70,8 +70,7 @@ bb1: (s:beginningele)= ## BeginningEle Element -Initial element at start of a branch. - +A BeginningEle element is an initial element at start of a branch. Under Construction... Element parameter groups associated with this element kind are: @@ -82,8 +81,6 @@ Element parameter groups associated with this element kind are: - [**ReferenceP**](#s:ref.params): Reference parameters. - [**TrackingP**](#s:tracking.params): Tracking parameters. -The length of this element is considered to be zero so if `length` is specified, it must be zero. - %--------------------------------------------------------------------------------------------------- (s:bend)= ## Bend Elements: RBend and SBend @@ -121,7 +118,9 @@ between `e1` and `e1_rect`, and `e2` and `e2_rect` satisfied. (s:converter)= ## Converter Element -Target to produce new species. EG: Positron converter. +A Converter element represents a target (plate) onto which +particles are slammed in order to generate +particles of a different type. For example, a tungsten plate which is bombarded with electrons to generate positrons. Under Construction... @@ -191,8 +190,8 @@ d01: %--------------------------------------------------------------------------------------------------- (s:egun)= ## EGun Element - -Electron gun. +An EGun element represents an electron gun and encompasses a region starting from the cathode were +the electrons are generated. Under Construction... @@ -211,7 +210,12 @@ Element parameter groups associated with this element kind are: (s:feedback)= ## Feedback Circuit -Element used to simulate a feedback circuit. +A Feedback element is a lord element used to simulate a feedback circuit. +It gathers information about particle trajectories from the inputs +and uses this +to either adjust beam trajectories in the outputs and/or adjust parameters in the outputs. +A feedback element could be used, for example, to simulate RF feedback systems or beam position +feedback, or cooling of a proton beam by a beam of electrons. Under Construction... @@ -221,12 +225,12 @@ Note: This element does not have a `length` nor an `s_position`. (s:fiducial)= ## Fiducial Element -Global coordinate system fiducial point. +A Fiducial element is used to fix the position and orientation of the reference orbit within the global +coordinate system at the location of the fiducial element. A fiducial element will affect the global +floor coordinates (§16.2) of elements both upstream and downstream of the fiducial element. Under Construction... -The length of this element is considered to be zero so if `length` is specified, it must be zero. - %--------------------------------------------------------------------------------------------------- (s:floorshift)= ## FloorShift Element @@ -248,8 +252,10 @@ Element parameter groups associated with this element kind are: (s:foil)= ## Foil Element -Material that can strip electrons from a particle. -Will also cause energy loss and diffusion. +A Foil element represents a planar sheet of material which can strip electrons from a particle. In +conjunction, there will be scattering of the particle trajectory as well as an associated energy loss. +Material that can strip electrons from a particle +will also cause energy loss and diffusion. Under Construction... @@ -268,7 +274,9 @@ The length of this element is considered to be zero so if `length` is specified, (s:fork)= ## Fork Element -Element used to connect lattice branches together. +A Fork element marks the start of an alternative branch for the beam (or X-rays or +other particles generated by the beam) to follow. +This element is used to connect lattice branches together. Under Construction... @@ -287,7 +295,11 @@ The length of this element is considered to be zero so if `length` is specified, (s:girder)= ## Girder Element -Element to support in space a group of other elements. +A Girder element is a support structure that orients the +elements that are attached to it in space. This element can +be used to simulate any rigid support structure and there are +no restrictions on how the lattice elements +that are supported are oriented with respect to one another. Under Construction... @@ -355,7 +367,8 @@ a case, the `BodyShiftP` parameter group can be used to misalign the BPM. (s:mask)= ## Mask Element -Collimation element. +A Mask element defines an aperture where the mask area can essentially have an arbitrary shape. +It is a collimation element to remove unwanted particles. Under Construction... @@ -374,7 +387,8 @@ Element parameter groups associated with this element kind are: (s:match)= ## Match Element -Orbit, Twiss, and dispersion matching element. +A Match element is used to match the orbit, Twiss, and dispersion parameters + between two locations. Under Construction... @@ -455,7 +469,10 @@ oct01w: (s:patch)= ## Patch Element -Crooked drift used to shift the reference curve. +A Patch element is an element used to shift the reference orbit and time. +A common application of this element is to orient two lines with respect +to each other. For example, +to orient an injection line with the ring it is injecting into. Under Construction... @@ -578,7 +595,9 @@ sol01w: (s:taylor)= ## Taylor Element -Taylor map element +A Taylor element is a Taylor map that maps the input orbital phase space and possibly spin coordinates +of a particle at the entrance end of the element to the output orbital and spin coordinates at the exit +end of the element. Under Construction... @@ -644,6 +663,7 @@ together with the [`placement`](#s:placement) construct within a `BeamLine` and %--------------------------------------------------------------------------------------------------- (s:wiggler)= ## Wiggler Element +A Wiggler element consists of a periodic array of alternating bending magnets. From a particle tracking perspective, it is equivalent to an undulator. Hereafter, the term "wiggler" will be used to denote either a wiggler or an undulator. Under Construction... From 073a64ffd2ba04ed02fb044d6b0ce4a56952ef6f Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Wed, 19 Nov 2025 20:56:34 -0800 Subject: [PATCH 05/21] remove the edit --- source/parameters/tracking.md | 1 - 1 file changed, 1 deletion(-) diff --git a/source/parameters/tracking.md b/source/parameters/tracking.md index d4f93c9..5665b84 100644 --- a/source/parameters/tracking.md +++ b/source/parameters/tracking.md @@ -10,7 +10,6 @@ tracking. The components of this group are: ```{code} yaml ReferenceP: - tracking_type: "" # [string] type of tracking ... ``` In Construction... From a2abadfa7ca733fd81f4e7d737e5a3bcfa40ec2d Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Thu, 20 Nov 2025 15:26:29 -0800 Subject: [PATCH 06/21] modified description of Instrument, Kicker, and RFCavity in element-kinds. --- source/element-kinds.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/source/element-kinds.md b/source/element-kinds.md index 7fd99ee..f7aca0b 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -309,7 +309,7 @@ Note: This element does not have a `length` nor an `s_position`. (s:instrument)= ## Instrument Element -Measurement element. +An Instrument element is a measurement element for diagnostics. Under Construction... @@ -328,7 +328,9 @@ Element parameter groups associated with this element kind are: (s:kicker)= ## Kicker Element -Particle kicker element. +A kicker element is an element that can deflect a beam in both planes. +It uses the hkick and vkick parameters to deflect the beam in +horizontal and vertical directions. Under Construction... @@ -520,6 +522,10 @@ q01w: (s:rfcavity)= ## RFCavity Element +An RFCavity element is an RF cavity without acceleration generally used in a storage ring. The main difference +between an rfcavity and an lcavity is that, unlike an lcavity, the reference energy through +an rfcavity is constant. + Under Construction... Element parameter groups associated with this element kind are: From 3bc7ab5861ee97c1999beccca07070cb8f62d3d4 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Thu, 20 Nov 2025 16:11:29 -0800 Subject: [PATCH 07/21] updated default values --- source/parameters/beambeam.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/parameters/beambeam.md b/source/parameters/beambeam.md index bea8a37..a741de4 100644 --- a/source/parameters/beambeam.md +++ b/source/parameters/beambeam.md @@ -7,15 +7,15 @@ from the opposite moving colliding beam. The inputs of `BeamBeamP` are: ```{code} yaml BeamBeamP: - sigma_x # The horizontal beam size of the opposite beam (default: 1 mm). - sigma_y # The vertical beam size of the opposite beam (default: 1 mm). - sigma_z # The longitudinal beam size of the opposite beam (default: 0 m). - alpha_x # The horizontal Twiss parameter alpha at interaction point (default: 0). - beta_x # The horizontal Twiss parameter beta at interaction point (default 1 m). - alpha_y # The vertical Twiss parameter alpha at interaction point (default 0 m). - beta_y # The vertical Twiss parameter beta at interaction point (default 1 m). - charge # The charge of the opposite beam (default: 1 for proton). - energy # The total energy in eV of the opposite beam (default: 1e12. - N_particle # Number of particles in the opposite beam (default: 0). + sigma_x: 0.001 # The horizontal beam size of the opposite beam (default: 1 mm). + sigma_y: 0.001 # The vertical beam size of the opposite beam (default: 1 mm). + sigma_z: 0.0 # The longitudinal beam size of the opposite beam (default: 0 m). + alpha_x: 0.0 # The horizontal Twiss parameter alpha at interaction point (default: 0). + beta_x: 1.0 # The horizontal Twiss parameter beta at interaction point (default 1 m). + alpha_y: 0.0 # The vertical Twiss parameter alpha at interaction point (default 0 m). + beta_y: 1.0 # The vertical Twiss parameter beta at interaction point (default 1 m). + charge: 1.0 # The charge of the opposite beam (default: 1 for proton). + energy: 1e12 # The total energy in eV of the opposite beam (default: 1e12. + N_particle: 0.0 # Number of particles in the opposite beam (default: 0). ``` From 4f48acd0e2e533bb7e1fdcaf41d2681808cf3ecf Mon Sep 17 00:00:00 2001 From: Ji Qiang <38738257+qianglbl@users.noreply.github.com> Date: Thu, 20 Nov 2025 16:16:01 -0800 Subject: [PATCH 08/21] Update source/element-kinds.md Co-authored-by: Chad Mitchell <46825199+cemitch99@users.noreply.github.com> --- source/element-kinds.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/element-kinds.md b/source/element-kinds.md index f7aca0b..df79a20 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -328,7 +328,7 @@ Element parameter groups associated with this element kind are: (s:kicker)= ## Kicker Element -A kicker element is an element that can deflect a beam in both planes. +A kicker element is an element that can deflect a beam transversely in both planes. It uses the hkick and vkick parameters to deflect the beam in horizontal and vertical directions. From dc9d463e76ec0ae1c925bd53a68fd2e1c5a5a13b Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Thu, 20 Nov 2025 16:34:05 -0800 Subject: [PATCH 09/21] modified the description of RFCavity element --- source/element-kinds.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/source/element-kinds.md b/source/element-kinds.md index df79a20..820e405 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -227,7 +227,7 @@ Note: This element does not have a `length` nor an `s_position`. A Fiducial element is used to fix the position and orientation of the reference orbit within the global coordinate system at the location of the fiducial element. A fiducial element will affect the global -floor coordinates (§16.2) of elements both upstream and downstream of the fiducial element. +floor coordinates of elements both upstream and downstream of the fiducial element. Under Construction... @@ -522,9 +522,7 @@ q01w: (s:rfcavity)= ## RFCavity Element -An RFCavity element is an RF cavity without acceleration generally used in a storage ring. The main difference -between an rfcavity and an lcavity is that, unlike an lcavity, the reference energy through -an rfcavity is constant. +An RFCavity element represents an RF cavity that accelerates or decelerates, and focuses or defocuses, a charged particle beam longitudinally and transversely using RF fields. Under Construction... From 93382d256aa8383d03f18a842d8d68fec4d2499f Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Thu, 20 Nov 2025 16:48:53 -0800 Subject: [PATCH 10/21] modied defaults ... --- source/parameters/initialparticle.md | 30 ++++++++++++++-------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/source/parameters/initialparticle.md b/source/parameters/initialparticle.md index 59cda66..7625d7d 100644 --- a/source/parameters/initialparticle.md +++ b/source/parameters/initialparticle.md @@ -8,20 +8,20 @@ The components of this group are: ```{code} yaml InitialParticleP: distribution_type: "" # [string] name of initial distribution type - sigx # RMS x = sqrt() - sigpx # RMS px = sqrt() - muxpx # - xoff # - pxoff # - sigy # RMS y = sqrt() - sigpy # RMS py = sqrt() - yoff # - pyoff # - muypy # - sigz # RMS z = sqrt() - sigpz # RMS pz = sqrt() - muzpz # - zoff # - pzoff # + sigma_x: null # RMS x = sqrt() + sigma_px: null # RMS px = sqrt() + mu_xpx: null # /(sigma_x*sigma_px) where <> denotes average over distribution + x_off: null # + px_off: null # + sigma_y: null # RMS y = sqrt() + sigma_py: null # RMS py = sqrt() + y_off: null # + py_off: null # + mu_ypy: null # /(sigma_y*sigma_py) + sigma_z: null # RMS z = sqrt() + sigma_pz: null # RMS pz = sqrt() + mu_zpz: null # /(sigma_z*sigma_pz) + z_off: null # + pz_off: null # ``` From da9f34e6c7a01d8fcfcdead8abeb2f8fdb167465 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Fri, 21 Nov 2025 13:38:11 -0800 Subject: [PATCH 11/21] added other moments --- source/parameters/initialparticle.md | 46 ++++++++++++++++++---------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/source/parameters/initialparticle.md b/source/parameters/initialparticle.md index 7625d7d..1068534 100644 --- a/source/parameters/initialparticle.md +++ b/source/parameters/initialparticle.md @@ -3,25 +3,37 @@ ## InitialParticleP: Initial Particle Coordinates Parameters The `InitialParticleP` parameter group contains parameters for describing the -initial beam particle distribution. +initial beam particle distribution based on its first two moments. The components of this group are: ```{code} yaml InitialParticleP: - distribution_type: "" # [string] name of initial distribution type - sigma_x: null # RMS x = sqrt() - sigma_px: null # RMS px = sqrt() - mu_xpx: null # /(sigma_x*sigma_px) where <> denotes average over distribution - x_off: null # - px_off: null # - sigma_y: null # RMS y = sqrt() - sigma_py: null # RMS py = sqrt() - y_off: null # - py_off: null # - mu_ypy: null # /(sigma_y*sigma_py) - sigma_z: null # RMS z = sqrt() - sigma_pz: null # RMS pz = sqrt() - mu_zpz: null # /(sigma_z*sigma_pz) - z_off: null # - pz_off: null # + distribution_type: "" # [string] name of initial distribution type + x_off: null # , <> denotes average over distribution + px_off: null # + y_off: null # + py_off: null # + z_off: null # + pz_off: null # + sigma_x: null # RMS x = sqrt() + sigma_px: null # RMS px = sqrt() + sigma_y: null # RMS y = sqrt() + sigma_py: null # RMS py = sqrt() + sigma_z: null # RMS z = sqrt() + sigma_pz: null # RMS pz = sqrt() + mu_xpx: null # + mu_xy: null # + mu_xpy: null # + mu_xz: null # + mu_xpz: null # + mu_pxy: null # + mu_pxpy: null # + mu_pxz: null # + mu_pxpz: null # + mu_ypy: null # + mu_yz: null # + mu_ypz: null # + mu_pyz: null # + mu_pypz: null # + mu_zpz: null # ``` From 370c63aa4d092bb0668db044479f8cec1195a210 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Fri, 21 Nov 2025 16:19:05 -0800 Subject: [PATCH 12/21] made a few minor changes --- source/element-kinds.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/element-kinds.md b/source/element-kinds.md index 820e405..387d674 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -43,7 +43,6 @@ ack1: (s:beambeam)= ## BeamBeam Element -Element for simulating colliding beams. A BeamBeam element defines the parameters of a oppositely moving "strong" beam that generates electromagnetic fields at the interaction point. This strong beam is assumed to have a three-dimensional (3D) Gaussian density distribution. Element parameter groups associated with this element kind are: @@ -210,7 +209,7 @@ Element parameter groups associated with this element kind are: (s:feedback)= ## Feedback Circuit -A Feedback element is a lord element used to simulate a feedback circuit. +A Feedback element is an element used to simulate a feedback circuit. It gathers information about particle trajectories from the inputs and uses this to either adjust beam trajectories in the outputs and/or adjust parameters in the outputs. @@ -600,7 +599,7 @@ sol01w: ## Taylor Element A Taylor element is a Taylor map that maps the input orbital phase space and possibly spin coordinates -of a particle at the entrance end of the element to the output orbital and spin coordinates at the exit +of a particle at the entrance end of the element to the output orbital phase space and spin coordinates at the exit end of the element. Under Construction... From 9d2274b8274352bef4b157867d4e76ce6ccaed1f Mon Sep 17 00:00:00 2001 From: Ji Qiang <38738257+qianglbl@users.noreply.github.com> Date: Mon, 24 Nov 2025 12:00:00 -0800 Subject: [PATCH 13/21] Update source/element-kinds.md Co-authored-by: Chad Mitchell <46825199+cemitch99@users.noreply.github.com> --- source/element-kinds.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/element-kinds.md b/source/element-kinds.md index 387d674..118c26f 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -328,7 +328,7 @@ Element parameter groups associated with this element kind are: ## Kicker Element A kicker element is an element that can deflect a beam transversely in both planes. -It uses the hkick and vkick parameters to deflect the beam in +It uses a zero-order (electric or magnetic) multipole field, determined by parameters in MagneticMultipoleP or ElectricMultipoleP such as Kn0, to deflect the beam in horizontal and vertical directions. Under Construction... From eba1164311930c1600e66d9dcac74d24c070d750 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Mon, 24 Nov 2025 12:06:56 -0800 Subject: [PATCH 14/21] removed RMS size --- source/parameters/initialparticle.md | 56 ++++++++++++++-------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/source/parameters/initialparticle.md b/source/parameters/initialparticle.md index 1068534..159fef1 100644 --- a/source/parameters/initialparticle.md +++ b/source/parameters/initialparticle.md @@ -7,33 +7,33 @@ initial beam particle distribution based on its first two moments. The components of this group are: ```{code} yaml InitialParticleP: - distribution_type: "" # [string] name of initial distribution type - x_off: null # , <> denotes average over distribution - px_off: null # - y_off: null # - py_off: null # - z_off: null # - pz_off: null # - sigma_x: null # RMS x = sqrt() - sigma_px: null # RMS px = sqrt() - sigma_y: null # RMS y = sqrt() - sigma_py: null # RMS py = sqrt() - sigma_z: null # RMS z = sqrt() - sigma_pz: null # RMS pz = sqrt() - mu_xpx: null # - mu_xy: null # - mu_xpy: null # - mu_xz: null # - mu_xpz: null # - mu_pxy: null # - mu_pxpy: null # - mu_pxz: null # - mu_pxpz: null # - mu_ypy: null # - mu_yz: null # - mu_ypz: null # - mu_pyz: null # - mu_pypz: null # - mu_zpz: null # + distribution_type: "" # [string] name of initial distribution type + x_off: null # , <> denotes average over distribution + px_off: null # + y_off: null # + py_off: null # + z_off: null # + pz_off: null # + sigma_xx: null # + sigma_pxpx: null # + sigma_yy: null # + sigma_pypy: null # + sigma_zz: null # + sigma_pzpz: null # + mu_xpx: null # + mu_xy: null # + mu_xpy: null # + mu_xz: null # + mu_xpz: null # + mu_pxy: null # + mu_pxpy: null # + mu_pxz: null # + mu_pxpz: null # + mu_ypy: null # + mu_yz: null # + mu_ypz: null # + mu_pyz: null # + mu_pypz: null # + mu_zpz: null # ``` From 9e9cd5638db88cb2d9ef311ff1cc9c076cd0a993 Mon Sep 17 00:00:00 2001 From: Ji Qiang <38738257+qianglbl@users.noreply.github.com> Date: Tue, 25 Nov 2025 13:30:36 -0800 Subject: [PATCH 15/21] Update source/parameters/initialparticle.md Co-authored-by: Chad Mitchell <46825199+cemitch99@users.noreply.github.com> --- source/parameters/initialparticle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/parameters/initialparticle.md b/source/parameters/initialparticle.md index 159fef1..d85279f 100644 --- a/source/parameters/initialparticle.md +++ b/source/parameters/initialparticle.md @@ -20,7 +20,7 @@ InitialParticleP: sigma_pypy: null # sigma_zz: null # sigma_pzpz: null # - mu_xpx: null # + sigma_xpx: null # mu_xy: null # mu_xpy: null # mu_xz: null # From f1055b6c27ef42571da4ef2d0fc0cc2fbfb07924 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Tue, 25 Nov 2025 16:54:56 -0800 Subject: [PATCH 16/21] changed mu into sigma --- source/parameters/initialparticle.md | 52 ++++++++++++++-------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/source/parameters/initialparticle.md b/source/parameters/initialparticle.md index d85279f..d456387 100644 --- a/source/parameters/initialparticle.md +++ b/source/parameters/initialparticle.md @@ -8,32 +8,32 @@ The components of this group are: ```{code} yaml InitialParticleP: distribution_type: "" # [string] name of initial distribution type - x_off: null # , <> denotes average over distribution - px_off: null # - y_off: null # - py_off: null # - z_off: null # - pz_off: null # - sigma_xx: null # - sigma_pxpx: null # - sigma_yy: null # - sigma_pypy: null # - sigma_zz: null # - sigma_pzpz: null # + x_off: null # , <> denotes average over distribution + px_off: null # + y_off: null # + py_off: null # + z_off: null # + pz_off: null # + sigma_xx: null # + sigma_pxpx: null # + sigma_yy: null # + sigma_pypy: null # + sigma_zz: null # + sigma_pzpz: null # sigma_xpx: null # - mu_xy: null # - mu_xpy: null # - mu_xz: null # - mu_xpz: null # - mu_pxy: null # - mu_pxpy: null # - mu_pxz: null # - mu_pxpz: null # - mu_ypy: null # - mu_yz: null # - mu_ypz: null # - mu_pyz: null # - mu_pypz: null # - mu_zpz: null # + sigma_xy: null # + sigma_xpy: null # + sigma_xz: null # + sigma_xpz: null # + sigma_pxy: null # + sigma_pxpy: null # + sigma_pxz: null # + sigma_pxpz: null # + sigma_ypy: null # + sigma_yz: null # + sigma_ypz: null # + sigma_pyz: null # + sigma_pypz: null # + sigma_zpz: null # ``` From f4ea6057445729a3b55aa88c4f3ee1caa2e47f93 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Wed, 26 Nov 2025 08:17:05 -0800 Subject: [PATCH 17/21] fixed one element --- source/element-kinds.md | 1 + 1 file changed, 1 insertion(+) diff --git a/source/element-kinds.md b/source/element-kinds.md index 118c26f..8a5753d 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -80,6 +80,7 @@ Element parameter groups associated with this element kind are: - [**ReferenceP**](#s:ref.params): Reference parameters. - [**TrackingP**](#s:tracking.params): Tracking parameters. +The length of this element is considered to be zero so if `length` is specified, it must be zero. %--------------------------------------------------------------------------------------------------- (s:bend)= ## Bend Elements: RBend and SBend From 88c09622301e165224b4f0bf006fedd1010c382d Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Mon, 1 Dec 2025 14:56:32 -0800 Subject: [PATCH 18/21] put back zero length... --- source/element-kinds.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/element-kinds.md b/source/element-kinds.md index 8a5753d..368bbe5 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -65,6 +65,8 @@ bb1: energy: 1.0e10 N_particle: 1.0e11 +The length of this element is considered to be zero so if `length` is specified, it must be zero. + %--------------------------------------------------------------------------------------------------- (s:beginningele)= ## BeginningEle Element @@ -231,6 +233,8 @@ floor coordinates of elements both upstream and downstream of the fiducial eleme Under Construction... +The length of this element is considered to be zero so if `length` is specified, it must be zero. + %--------------------------------------------------------------------------------------------------- (s:floorshift)= ## FloorShift Element From 8e081673f5edbc6ebf9992837be3cd983062f664 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Wed, 3 Dec 2025 12:44:08 -0800 Subject: [PATCH 19/21] modified ACkicker --- source/element-kinds.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/source/element-kinds.md b/source/element-kinds.md index 368bbe5..662f119 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -18,6 +18,7 @@ cleo: # [string] user-defined name An ACKicker element simulates a time-dependent kicker. It is like a Kicker element except that the field varies in time. +This element requires a user supplied time-dependent expression. Element parameter groups associated with this element kind are: - [**ACKickerP**](#s:ackicker.params): AC kicker parameters. @@ -34,10 +35,8 @@ Example: ack1: kind: ACKicker length: 0.3 - t_offset: 0.1e-8 - scale_multipoles: = F - b1: = 0.27 - amplitude_vs_time: = {(-1.2e-6, 0.02), ... } + t_0: 0.0 + t : 1e-8 %--------------------------------------------------------------------------------------------------- (s:beambeam)= From 2cf6eeb80c90516b0cc623569456a4763712d697 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Wed, 3 Dec 2025 14:55:54 -0800 Subject: [PATCH 20/21] updated --- source/parameters/beambeam.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/parameters/beambeam.md b/source/parameters/beambeam.md index a741de4..e1c18e5 100644 --- a/source/parameters/beambeam.md +++ b/source/parameters/beambeam.md @@ -7,15 +7,15 @@ from the opposite moving colliding beam. The inputs of `BeamBeamP` are: ```{code} yaml BeamBeamP: - sigma_x: 0.001 # The horizontal beam size of the opposite beam (default: 1 mm). - sigma_y: 0.001 # The vertical beam size of the opposite beam (default: 1 mm). - sigma_z: 0.0 # The longitudinal beam size of the opposite beam (default: 0 m). - alpha_x: 0.0 # The horizontal Twiss parameter alpha at interaction point (default: 0). - beta_x: 1.0 # The horizontal Twiss parameter beta at interaction point (default 1 m). - alpha_y: 0.0 # The vertical Twiss parameter alpha at interaction point (default 0 m). - beta_y: 1.0 # The vertical Twiss parameter beta at interaction point (default 1 m). - charge: 1.0 # The charge of the opposite beam (default: 1 for proton). - energy: 1e12 # The total energy in eV of the opposite beam (default: 1e12. - N_particle: 0.0 # Number of particles in the opposite beam (default: 0). + sigma_x: 0.001 # [m] The horizontal beam size of the opposite beam with default value of 1 mm. + sigma_y: 0.001 # [m] The vertical beam size of the opposite beam with default value of 1 mm. + sigma_z: 0.0 # [m] The longitudinal beam size of the opposite beam with default value of 0 m. + alpha_x: 0.0 # [unitless] The horizontal Twiss parameter alpha at interaction point with default value of 0. + beta_x: 1.0 # [m] The horizontal Twiss parameter beta at interaction point with default value of 1 m. + alpha_y: 0.0 # [unitless] The vertical Twiss parameter alpha at interaction point default value of 0 m. + beta_y: 1.0 # [m] The vertical Twiss parameter beta at interaction point with default value of 1 m. + charge: 1.0 # [unitless] The charge of the opposite beam with default value of 1 for proton. + energy: 1e12 # [eV] The total energy in eV of the opposite beam with default value of 1e12. + N_particle: 0.0 # [unitless] Number of particles in the opposite beam with default value of 0. ``` From cf3205a72931ad1a6dc68c0ab3e3ec3a2db9bbd3 Mon Sep 17 00:00:00 2001 From: Ji Qiang Date: Wed, 3 Dec 2025 16:08:06 -0800 Subject: [PATCH 21/21] fixed --- source/element-kinds.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/source/element-kinds.md b/source/element-kinds.md index 662f119..7959524 100644 --- a/source/element-kinds.md +++ b/source/element-kinds.md @@ -160,9 +160,10 @@ Example: ```{code} yaml cc1: kind: CrabCavity - frequency: 394.0e6 - phase: 0.0 - voltage: 1.0e6 + RFP: + frequency: 394.0e6 + phase: 0.0 + voltage: 1.0e6 %--------------------------------------------------------------------------------------------------- (s:drift)= @@ -331,7 +332,7 @@ Element parameter groups associated with this element kind are: (s:kicker)= ## Kicker Element -A kicker element is an element that can deflect a beam transversely in both planes. +A Kicker element is an element that can deflect a beam transversely in both planes. It uses a zero-order (electric or magnetic) multipole field, determined by parameters in MagneticMultipoleP or ElectricMultipoleP such as Kn0, to deflect the beam in horizontal and vertical directions. @@ -352,7 +353,7 @@ Element parameter groups associated with this element kind are: (s:marker)= ## Marker Element -Zero length element to mark a particular position. +A Marker element is a zero length element to mark a particular position. The main purpose of this element is to name a position in the beamline. `Marker` elements has a unit transport map. That is, a particle's phase space coordinates are not altered with passage through the element