Update several parameters, element kinds #127

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

List of new or updated parameters:

BeamBeamP
InitialParticleP
TrackingP

List of new or updated element kinds:

ACKicker
BeamBeam
BeginningEle
Converter
CrabCavity
EGun
Feedback
Fiducial
Foil
Fork
Girder
Instrument
kicker
Mask
Match
Patch
RFCavity
Taylor
Wiggler

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.

source/parameters/tracking.md

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.

@EZoni I can push a commit with this change.

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.

I agree a combination one might be better.

I modified the description of the RFCavity element as follows:
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.

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?

If we don't assume a Gaussian distribution, then we might need more parameters than just sigmas for this element. On the other hand, without Gaussian assumption does allow more flexibility.

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?

Probably not. I assume those two are parameters needed for this element.

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 Agreed. I think that sigma_xpx might be better. I will add other moments.

Would it be possible to use a clearer notation for some of these quantities, e.g., <x p_x> instead of <xpx> (hence also <p_x> instead of <px>, etc.)?

source/parameters/initialparticle.md

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 Agreed. For an expression, we need to specify the form and number of parameters needed.

@DavidSagan This requires more discussion of how to support expressions. Maybe we should discuss during the PALS meeting.

source/element-kinds.md

EZoni · 2025-12-03T22:39:07Z

@DavidSagan

When you have some time, could you resolve the conversations that you think have been resolved (I mean literally clicking the button to resolve them)? Just to understand better what remains to be done in this PR.

EZoni · 2025-12-03T22:40:54Z

source/parameters/beambeam.md

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


I think this doesn't follow the conventions we agreed on in #127 (comment), namely

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.

Note that the comments here were meant to explain the meaning of the convention. For example, I don't think it's necessary to repeat the default values in the comment.

@EZoni I will clean up this a bit.

DavidSagan · 2025-12-03T22:46:34Z

source/element-kinds.md

+cc1:
+  kind: CrabCavity
+  frequency: 394.0e6 
+  phase: 0.0
+  voltage: 1.0e6


Parameters like frequency are in the RFP group so a change is needed here.

@DavidSagan fixed.

EZoni · 2025-12-03T22:49:38Z

source/element-kinds.md

 ## Kicker Element

-Particle kicker element.
+A kicker element is an element that can deflect a beam transversely in both planes. 


Should this be Kicker (capital K)?

Suggested change

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.

@EZoni fixed.

DavidSagan · 2025-12-03T22:52:53Z

source/parameters/initialparticle.md

+  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_xx:      null         # <x^2>
+  sigma_pxpx:    null         # <px^2>
+  sigma_yy:      null         # <y^2>
+  sigma_pypy:    null         # <py^2>
+  sigma_zz:      null         # <z^2>
+  sigma_pzpz:    null         # <pz^2>
+  sigma_xpx:     null         # <xpx> 
+  sigma_xy:      null         # <xy> 
+  sigma_xpy:     null         # <xpy> 
+  sigma_xz:      null         # <xz> 
+  sigma_xpz:     null         # <xpz> 
+  sigma_pxy:     null         # <pxy> 
+  sigma_pxpy:    null         # <pxpy> 
+  sigma_pxz:     null         # <pxz> 
+  sigma_pxpz:    null         # <pxpz> 
+  sigma_ypy:     null         # <ypy>
+  sigma_yz:      null         # <yz>
+  sigma_ypz:     null         # <ypz>
+  sigma_pyz:     null         # <pyz>
+  sigma_pypz:    null         # <pypz>
+  sigma_zpz:     null         # <zpz>


How about using numbers for subscripts? EG: sigma_24 instead of sigma_pypy? I could go either way but I just thought this should be considered.

@DavidSagan The reason that I used sigma_pypy instead of sigma_24 is because we have z_off and pz_off defined first. If we use sigma_24, should we change the first 6 centroid definition as off_1, off_2,... or mean_1, mean_2,...?

modified three files

ff8dec3

DavidSagan reviewed Nov 17, 2025

View reviewed changes

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

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

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

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

source/element-kinds.md Show resolved Hide resolved

qianglbl added 2 commits November 26, 2025 08:17

fixed one element

f4ea605

put back zero length...

88c0962

ax3l added the element parameters element parameters (properties, attributes) label Dec 3, 2025

EZoni requested review from DavidSagan and EZoni December 3, 2025 17:35

modified ACkicker

8e08167

EZoni reviewed Dec 3, 2025

View reviewed changes

EZoni changed the title ~~Update BeamBeamP, InitialParticleP, TrackingP~~ Update several parameters, element kinds Dec 3, 2025

DavidSagan reviewed Dec 3, 2025

View reviewed changes

EZoni reviewed Dec 3, 2025

View reviewed changes

DavidSagan reviewed Dec 3, 2025

View reviewed changes

qianglbl added 2 commits December 3, 2025 14:55

updated

2cf6eeb

fixed

cf3205a

		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.

	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.

Update several parameters, element kinds #127

Are you sure you want to change the base?

Update several parameters, element kinds #127

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

qianglbl commented Nov 17, 2025 •

edited by EZoni

Loading

EZoni Nov 19, 2025 •

edited

Loading

cemitch99 Nov 20, 2025 •

edited

Loading