Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions source/parameters/beambeam.md
Original file line number Diff line number Diff line change
@@ -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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For hourglass effect will be beta and alpha Twiss parameters.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree.

charge # The charge of the opposite beam (default: 1 for proton).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Member

@EZoni EZoni Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes that looks good.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@EZoni I can push a commit with this change.

energy # The total energy in eV of the opposite beam.
Npart # Number of charged particles of the opposite beam.
```

23 changes: 22 additions & 1 deletion source/parameters/initialparticle.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed.

sigx # RMS x = sqrt(<x^2>)
sigpx # RMS px = sqrt(<px^2>)
muxpx # <xpx>
xoff # <x>
pxoff # <px>
sigy # RMS y = sqrt(<y^2>)
sigpy # RMS py = sqrt(<py^2>)
yoff # <y>
pyoff # <py>
muypy # <ypy>
sigz # RMS z = sqrt(<z^2>)
sigpz # RMS pz = sqrt(<pz^2>)
muzpz # <zpz>
zoff # <z>
pzoff # <pz>
```

10 changes: 10 additions & 0 deletions source/parameters/tracking.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

start_loc: "" # [string] Where tracking starts
end_loc: "" # [string] Where tracking ends
...
```
In Construction...