Update BeamBeamP, InitialParticleP, TrackingP #127

qianglbl · 2025-11-17T19:14:20Z

No description provided.

EZoni · 2025-11-17T19:18:10Z

I just edited the PR description and removed the template text, so you can add a description specific to the changes in this PR.

DavidSagan · 2025-11-17T19:32:19Z

source/parameters/tracking.md

+  start_loc: ""     # [string] Where tracking starts
+  end_loc: ""       # [string] Where tracking ends


TrackingP is a parameter group for individual lattice elements. If start_loc and end_loc are global parameters, these parameters should not be in TrackingP. Also if these parameters are particular to one type of simulation and not others, the parameters should be structured within a sub-parameter group.

If TrackingP is for individual lattice elements, don't you need to specify their starting locations w.r.p a global origin?

I'm not sure what you mean by "locations w.r.p a global origin" If you are talking about "floor" coordinates then there is FloorP.

David, what parameters in your mind for TrackingP?

See https://github.com/pals-project/pals/pull/119/files#diff-b31d07bf5b91fc4d9071400bebdba5dfa63f852f178f80b23d1612e1892b05f1

Should one use that parameter to indicate what tracking method is used in different programs?

I don't know what you mean by "that parameter". There could be an ImpactT subgroup of TrackingP for example.

Ok, I see your point.

One possibility is to remove your edits of TrackingP since my PR adds documentation.

@DavidSagan OK, I removed my edits of trackingP.

DavidSagan · 2025-11-18T01:22:08Z

source/parameters/beambeam.md

+  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).


Better would be
"charge: 0 # [unitless] Charge of particles of the opposite beam."
Also see the syntax used parameters (Example: https://pals-project.readthedocs.io/en/latest/element-parameters.html#bodyshiftp-element-body-orientation-and-position-parameters)

@DavidSagan

Can you remind me/us, what syntax or style convention do we use to list parameters that don't have a default?

Is this it?

MyParameterGroupP: param1: 12.3 # [eV] A parameter with default value 12.3 in units of eV. param2: # [eV] A parameter without default value in units of eV. param3: # [unitless] A parameter without default value, unitless.

Or do we follow a different convention?

Also, how do you write the default specification if it's more intricate than a single value (e.g., with the for protons extra condition in this case)? Like this maybe?

MyParameterGroupP: param1: 12.3 (for protons) # [eV] A parameter with default value 12.3 (conditional) in units of eV.

Okay, so based on #129, this would be

MyParameterGroupP: param1: 12.3 # [eV] A parameter with default value 12.3 in units of eV. param2: null # [eV] A parameter without default value in units of eV. param3: null # [unitless] A parameter without default value, unitless.

correct?

I just put in a PR to clarify that null can be used to signify a lack of a default.

As for the syntax to use when there are multiple defaults, I have not thought about it.

Perfect.

So, @qianglbl, for now I think we would need to rewrite the lists in this PR following the convention described in my comment above, #127 (comment), namely again

MyParameterGroupP: param1: 12.3 # [eV] A parameter with default value 12.3 in units of eV. param2: null # [eV] A parameter without default value in units of eV. param3: null # [unitless] A parameter without default value, unitless.

Please let me know if you want to push a commit with this change or if I shall do it.

Yes that looks good.

DavidSagan · 2025-11-18T01:42:39Z

source/parameters/beambeam.md

+  xdisp     # The horizontal displacement of the opposite beam (default: 0 m).
+  ydisp     # The vertical displacement of the opposite beam (default: 0 m).


Displacement and orientation can be handled by the BodyShiftP parameter group and do not need to be duplicated.

DavidSagan · 2025-11-18T01:43:48Z

source/parameters/beambeam.md

+  sigx      # The horizontal beam size of the opposite beam (default: 0 m).
+  sigy      # The vertical beam size of the opposite beam (default: 0 m).


For hourglass effect will be beta and alpha Twiss parameters.

The sigma is used to calculate beam-beam force kicks. For the hourglass effect, do you mean in beam-beam kick or luminosity?

The hourglass effect is the change in beam size due to changing Twiss beta as a function of longitudinal position.

It looks like you are thinking about 3D beam-beam instead of 2D beam-beam effects. In that case, one should add sigma_z too.

@DavidSagan I updated the beambeam.md following the above discussion and pushed it back.

DavidSagan · 2025-11-18T01:46:54Z

source/parameters/initialparticle.md

+The components of this group are:
+```{code} yaml
+InitialParticleP:
+  Distype: ""    # [string] name of initial distribution type


To be portable, the possible settings of distype (I think better is distribution_type) need to be documented.

DavidSagan · 2025-11-19T13:23:15Z

source/parameters/beambeam.md

+  sigx      # The horizontal beam size of the opposite beam (default: 0 m).
+  sigy      # The vertical beam size of the opposite beam (default: 0 m).


This brings up the question as to whether the standard should use fuller names like sigma_x and sigma_y or shortened names like we have here.

@DavidSagan If we have used fuller names in the other parts of the standard, we should probably use the fuller names to be consistent.

DavidSagan · 2025-11-19T13:28:04Z

source/parameters/tracking.md

+The components of this group are:
+```{code} yaml
+ReferenceP:
+  tracking_type: "" # [string] type of tracking


This is in contrast to https://github.com/pals-project/pals/pull/119/files#diff-b31d07bf5b91fc4d9071400bebdba5dfa63f852f178f80b23d1612e1892b05f1 where the type of tracking can be set on a per-program basis. This raises the question as to whether a overall tracking method setting is useful.

source/parameters/beambeam.md

element-kinds.

cemitch99 · 2025-11-20T23:55:07Z

source/element-kinds.md


+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.


Note: This is how things are done in the BMAD manual, but I'm not sure we should do this in PALS. Note that David didn't add a separate LCavity element or parameters, so I suspect he intended to combine the functionality into one element kind.

This should be discussed. The only difference in Bmad between RFCavity and Lcavity is the reference energy change.

source/element-kinds.md

DavidSagan · 2025-11-21T00:12:50Z

source/element-kinds.md

 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.


Do we really want to have the assumption that the strong beam is Gaussian. If a program does not make this assumption then what kind of lattice element should it use?

DavidSagan · 2025-11-21T00:14:06Z

source/element-kinds.md

-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.


Section numbers should not be hard coded.

DavidSagan · 2025-11-21T00:15:40Z

source/element-kinds.md

+It uses the hkick and vkick parameters to deflect the beam in
+horizontal and vertical directions.


Do we really want different names for kicks as opposed to zeroth order multipoles?

Co-authored-by: Chad Mitchell <[email protected]>

DavidSagan · 2025-11-21T02:18:54Z

source/parameters/initialparticle.md

+InitialParticleP:
+  distribution_type: ""    # [string] name of initial distribution type
+  sigma_x: null            # RMS x = sqrt(<x^2>)
+  sigma_px: null           # RMS px = sqrt(<px^2>)
+  mu_xpx: null             # <xpx>/(sigma_x*sigma_px) where <> denotes average over distribution
+  x_off: null              # <x>
+  px_off: null             # <px>
+  sigma_y: null            # RMS y = sqrt(<y^2>)
+  sigma_py: null           # RMS py = sqrt(<py^2>)
+  y_off: null              # <y>
+  py_off: null             # <py>
+  mu_ypy: null             # <ypy>/(sigma_y*sigma_py)
+  sigma_z: null            # RMS z = sqrt(<z^2>)
+  sigma_pz: null           # RMS pz = sqrt(<pz^2>)
+  mu_zpz: null             # <zpz>/(sigma_z*sigma_pz)
+  z_off: null              # <z>
+  pz_off: null             # <pz>
+```


There are 21 moments so setting any should be available. How about something like sigma_xpy or sigma_14 for <x*py>. Also something like <xpx>/(sigma_x*sigma_px) will be singular if sigma_x or sigma_px are zero and these are redundant if sigma_14 notation is used.

DavidSagan · 2025-11-24T18:45:54Z

source/parameters/initialparticle.md

+InitialParticleP:
+  distribution_type: ""  # [string] name of initial distribution type
+  x_off:    null         # <x>, <> denotes average over distribution
+  px_off:   null         # <px>
+  y_off:    null         # <y>
+  py_off:   null         # <py>
+  z_off:    null         # <z>
+  pz_off:   null         # <pz>
+  sigma_x:  null         # RMS x = sqrt(<x^2>)
+  sigma_px: null         # RMS px = sqrt(<px^2>)
+  sigma_y:  null         # RMS y = sqrt(<y^2>)
+  sigma_py: null         # RMS py = sqrt(<py^2>)
+  sigma_z:  null         # RMS z = sqrt(<z^2>)
+  sigma_pz: null         # RMS pz = sqrt(<pz^2>)
+  mu_xpx:   null         # <xpx> 
+  mu_xy:    null         # <xy> 
+  mu_xpy:   null         # <xpy> 
+  mu_xz:    null         # <xz> 
+  mu_xpz:   null         # <xpz> 
+  mu_pxy:   null         # <pxy> 
+  mu_pxpy:  null         # <pxpy> 
+  mu_pxz:   null         # <pxz> 
+  mu_pxpz:  null         # <pxpz> 
+  mu_ypy:   null         # <ypy>
+  mu_yz:    null         # <yz>
+  mu_ypz:   null         # <ypz>
+  mu_pyz:   null         # <pyz>
+  mu_pypz:  null         # <pypz>
+  mu_zpz:   null         # <zpz>


I suggest a uniform naming for the sigma matrix. EG: sigma_xx = <xx>, etc. Or can use covar in place of sigma. Another naming convention, if we want to contemplate PALS supporting differing phase space coordinate systems, is to use numbers for subscripts. EG: sigma_12 = <x*py>.

source/element-kinds.md

Co-authored-by: Chad Mitchell <[email protected]>

source/parameters/initialparticle.md

Co-authored-by: Chad Mitchell <[email protected]>

DavidSagan · 2025-11-26T15:57:19Z

source/element-kinds.md

+  t_offset: 0.1e-8
+  scale_multipoles: = F
+  b1: = 0.27
+  amplitude_vs_time: = {(-1.2e-6, 0.02), ... }


This is derived from Bmad and I don't think this is a good fit for PALS. My feeling is that using an expression to define the AC waveform as a function of time is cleaner. In any case, all new parameters need to be well defined.

DavidSagan · 2025-11-26T15:59:28Z

source/element-kinds.md

 - [**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.


Why is this taken out?

modified three files

ff8dec3

DavidSagan reviewed Nov 17, 2025

View reviewed changes

DavidSagan reviewed Nov 18, 2025

View reviewed changes

modified 3 parameter files.

0fbf840

DavidSagan reviewed Nov 19, 2025

View reviewed changes

EZoni changed the title ~~modified three files~~ Update BeamBeamP, InitialParticleP, TrackingP Nov 19, 2025

EZoni reviewed Nov 19, 2025

View reviewed changes

source/parameters/beambeam.md Show resolved Hide resolved

EZoni reviewed Nov 19, 2025

View reviewed changes

source/parameters/beambeam.md Outdated Show resolved Hide resolved

qianglbl added 4 commits November 19, 2025 15:08

updated beambeam.md and element-kinds.md

efc8715

added description of elements in the element-kinds.md

fb79813

remove the edit

073a64f

modified description of Instrument, Kicker, and RFCavity in

a2abadf

element-kinds.

cemitch99 reviewed Nov 20, 2025

View reviewed changes

source/element-kinds.md Outdated Show resolved Hide resolved

cemitch99 reviewed Nov 21, 2025

View reviewed changes

source/element-kinds.md Show resolved Hide resolved

updated default values

3bc7ab5

DavidSagan reviewed Nov 21, 2025

View reviewed changes

qianglbl and others added 3 commits November 20, 2025 16:16

Update source/element-kinds.md

4f48acd

Co-authored-by: Chad Mitchell <[email protected]>

modified the description of RFCavity element

dc9d463

modied defaults ...

93382d2

DavidSagan reviewed Nov 21, 2025

View reviewed changes

qianglbl added 2 commits November 21, 2025 13:38

added other moments

da9f34e

made a few minor changes

370c63a

DavidSagan reviewed Nov 24, 2025

View reviewed changes

cemitch99 reviewed Nov 24, 2025

View reviewed changes

source/element-kinds.md Outdated Show resolved Hide resolved

qianglbl and others added 2 commits November 24, 2025 12:00

Update source/element-kinds.md

9d2274b

Co-authored-by: Chad Mitchell <[email protected]>

removed RMS size

eba1164

cemitch99 reviewed Nov 25, 2025

View reviewed changes

source/parameters/initialparticle.md Outdated Show resolved Hide resolved

qianglbl and others added 2 commits November 25, 2025 13:30

Update source/parameters/initialparticle.md

9e9cd56

Co-authored-by: Chad Mitchell <[email protected]>

changed mu into sigma

f1055b6

cemitch99 approved these changes Nov 26, 2025

View reviewed changes

DavidSagan reviewed Nov 26, 2025

View reviewed changes

fixed one element

f4ea605

		start_loc: "" # [string] Where tracking starts
		end_loc: "" # [string] Where tracking ends

		xdisp # The horizontal displacement of the opposite beam (default: 0 m).
		ydisp # The vertical displacement of the opposite beam (default: 0 m).

		sigx # The horizontal beam size of the opposite beam (default: 0 m).
		sigy # The vertical beam size of the opposite beam (default: 0 m).

		It uses the hkick and vkick parameters to deflect the beam in
		horizontal and vertical directions.

Update BeamBeamP, InitialParticleP, TrackingP #127

Are you sure you want to change the base?

Update BeamBeamP, InitialParticleP, TrackingP #127

Uh oh!

Conversation

qianglbl commented Nov 17, 2025 • edited by EZoni Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EZoni commented Nov 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

EZoni Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cemitch99 Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

qianglbl commented Nov 17, 2025 •

edited by EZoni

Loading

EZoni Nov 19, 2025 •

edited

Loading

cemitch99 Nov 20, 2025 •

edited

Loading