Skip to content

Commit 41ede47

Browse files
ChristopherMayesChristopherMayes
authored
Merge pull request #129 from ChristopherMayes/stat_standards
YAML-Based Statistics Standard
2 parents 78a63a4 + 883bce1 commit 41ede47

File tree

14 files changed

+2330
-19
lines changed

14 files changed

+2330
-19
lines changed

‎.github/workflows/gh-pages.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@ jobs:
3232
shell: bash -l {0}
3333
run: |
3434
scripts/execute_notebooks.bash
35+
- name: Generate statistics standard docs
36+
shell: bash -l {0}
37+
run: python scripts/generate_statistics_docs.py
3538
- name: Build Docs
3639
shell: bash -l {0}
3740
run: mkdocs build

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,13 @@ __pycache__/
33
*.py[cod]
44
*$py.class
55

6+
# Generated documentation
7+
docs/api/statistics_standard.md
8+
docs/api/computed_statistics.md
9+
10+
# Generated computed statistics (runtime-generated)
11+
pmd_beamphysics/standards/computed_statistics.yaml
12+
613
# C extensions
714
*.so
815

‎docs/examples/units.ipynb‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,66 @@
9191
"sqrt_unit(u1)"
9292
]
9393
},
94+
{
95+
"cell_type": "markdown",
96+
"metadata": {},
97+
"source": [
98+
"## Power notation\n",
99+
"\n",
100+
"Units can be raised to powers using `^` notation. Integer, decimal, and fractional powers are supported:"
101+
]
102+
},
103+
{
104+
"cell_type": "code",
105+
"execution_count": null,
106+
"metadata": {},
107+
"outputs": [],
108+
"source": [
109+
"# Integer and decimal powers\n",
110+
"pmd_unit(\"m^2\"), pmd_unit(\"m^-1\"), pmd_unit(\"m^0.5\")"
111+
]
112+
},
113+
{
114+
"cell_type": "code",
115+
"execution_count": null,
116+
"metadata": {},
117+
"outputs": [],
118+
"source": [
119+
"# Fractional powers using parentheses: m^(-3/2), m^(1/2)\n",
120+
"pmd_unit(\"m^(-3/2)\"), pmd_unit(\"m^(3/2)\")"
121+
]
122+
},
123+
{
124+
"cell_type": "code",
125+
"execution_count": null,
126+
"metadata": {},
127+
"outputs": [],
128+
"source": [
129+
"# sqrt() notation is equivalent to ^(1/2)\n",
130+
"pmd_unit(\"sqrt(m)\"), pmd_unit(\"m^(1/2)\")"
131+
]
132+
},
133+
{
134+
"cell_type": "code",
135+
"execution_count": null,
136+
"metadata": {},
137+
"outputs": [],
138+
"source": [
139+
"# Powers work in compound expressions\n",
140+
"pmd_unit(\"eV/c*m^(-1/2)\")"
141+
]
142+
},
143+
{
144+
"cell_type": "code",
145+
"execution_count": null,
146+
"metadata": {},
147+
"outputs": [],
148+
"source": [
149+
"# Check that fractional dimensions are preserved\n",
150+
"u = pmd_unit(\"m^(-3/2)\")\n",
151+
"u.unitDimension # Length dimension is -1.5"
152+
]
153+
},
94154
{
95155
"cell_type": "markdown",
96156
"metadata": {},

‎docs/statistics_schema.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# Statistics Standard Schema
2+
3+
This document describes the YAML schema used to define particle beam statistics in openPMD-beamphysics. The schema provides a structured, maintainable format for documenting statistical quantities with their mathematical definitions, units, and references.
4+
5+
## Schema Version
6+
7+
The current schema version is **1.0**.
8+
9+
The schema version is specified at the top level of the YAML file:
10+
11+
```yaml
12+
schema_version: "1.0"
13+
```
14+
15+
### Versioning Policy
16+
17+
- **Major version** (X.0): Breaking changes that require updates to existing entries
18+
- **Minor version** (1.X): Additive changes (new optional fields, new categories)
19+
20+
## File Location
21+
22+
The statistics standard is defined in:
23+
24+
```
25+
pmd_beamphysics/statistics_standard/statistics_standard.yaml
26+
```
27+
28+
## Top-Level Structure
29+
30+
```yaml
31+
schema_version: "1.0"
32+
33+
categories:
34+
- id: <category_id>
35+
name: <Category Name>
36+
description: <Category description>
37+
38+
statistics:
39+
- label: <statistic_label>
40+
mathlabel: <LaTeX string>
41+
units: <unit string>
42+
description: <verbose description>
43+
reference: <reference string>
44+
category: <category_id>
45+
# Optional fields:
46+
formula: <LaTeX formula>
47+
reference_url: <URL>
48+
aliases: [<alias1>, <alias2>]
49+
```
50+
51+
## Categories
52+
53+
Categories group related statistics for organized documentation. Each category has:
54+
55+
| Field | Type | Required | Description |
56+
|-------|------|----------|-------------|
57+
| `id` | string | Yes | Unique identifier used to reference from statistics |
58+
| `name` | string | Yes | Human-readable category name |
59+
| `description` | string | Yes | Brief description of the category |
60+
61+
### Standard Categories
62+
63+
| ID | Name | Description |
64+
|----|------|-------------|
65+
| `coordinates` | Phase Space Coordinates | Basic position and momentum coordinates |
66+
| `time` | Time Coordinate | Time-related quantities |
67+
| `relativistic` | Relativistic Quantities | Energy, momentum, velocity factors |
68+
| `slopes` | Transverse Slopes | Angular divergence quantities |
69+
| `polar` | Polar/Cylindrical Coordinates | Cylindrical coordinate representations |
70+
| `normalized` | Normalized Coordinates | Courant-Snyder normalized coordinates |
71+
| `emittance` | Emittance | Phase space volume measures |
72+
| `twiss` | Twiss Parameters | Courant-Snyder lattice functions |
73+
| `beam` | Beam Properties | Integrated beam properties |
74+
| `particle` | Particle Properties | Individual particle properties |
75+
76+
## Statistics Entry Fields
77+
78+
### Required Fields
79+
80+
| Field | Type | Description | Example |
81+
|-------|------|-------------|---------|
82+
| `label` | string | Code key used to access the statistic in ParticleGroup | `"norm_emit_x"` |
83+
| `mathlabel` | string | LaTeX string for mathematical symbol (without `$` delimiters) | `"\epsilon_{n,x}"` |
84+
| `units` | string | Unit string compatible with `pmd_unit` | `"m"`, `"eV/c"`, `"1"` |
85+
| `description` | string | Verbose human-readable description | `"Normalized RMS emittance..."` |
86+
| `reference` | string | Citation or reference for the definition | `"Courant & Snyder, Ann. Phys. 3 (1958)"` |
87+
| `category` | string | Category ID this statistic belongs to | `"emittance"` |
88+
89+
### Optional Fields
90+
91+
| Field | Type | Description | Example |
92+
|-------|------|-------------|---------|
93+
| `formula` | string | LaTeX formula for derived quantities | `"\epsilon = \sqrt{\det(\Sigma)}"` |
94+
| `reference_url` | string | URL/DOI link to the reference | `"https://doi.org/10.1016/..."` |
95+
| `aliases` | list[string] | Alternative labels for the same quantity | `["emit_x", "emittance_x"]` |
96+
97+
## Field Validation Rules
98+
99+
### `label`
100+
101+
- Must be a valid Python identifier or contain only alphanumeric characters, underscores, and `/`
102+
- Must be unique across all statistics entries
103+
- Should match the attribute/key name used in `ParticleGroup`
104+
- Examples: `"x"`, `"norm_emit_x"`, `"z/c"`, `"twiss_beta_x"`
105+
106+
### `mathlabel`
107+
108+
- Must be valid LaTeX (will be wrapped in `$...$` for rendering)
109+
- Use raw strings or escape backslashes properly in YAML
110+
- Common patterns:
111+
- Greek letters: `\alpha`, `\beta`, `\gamma`, `\epsilon`
112+
- Subscripts: `x_0`, `p_x`, `\beta_x`
113+
- Overlines: `\overline{x}`
114+
- Text in math: `\text{kinetic}`, `\mathrm{avg}`
115+
116+
### `units`
117+
118+
- Must be a unit string recognized by `pmd_unit` or a compound expression
119+
- Use `"1"` for dimensionless quantities
120+
- Standard units:
121+
- Length: `"m"`
122+
- Time: `"s"`
123+
- Energy: `"eV"`
124+
- Momentum: `"eV/c"`
125+
- Charge: `"C"`
126+
- Current: `"A"`
127+
- Angle: `"rad"`
128+
- Compound units: `"m*eV/c"`, `"m^2"`, `"1/m"`
129+
- Special: `"sqrt(m)"` for normalized coordinates
130+
131+
### `description`
132+
133+
- Should be a complete sentence or phrase
134+
- Include physical meaning and context
135+
- Use YAML multiline syntax for long descriptions:
136+
137+
```yaml
138+
description: >-
139+
Normalized RMS emittance in the horizontal plane.
140+
This quantity is invariant under linear symplectic transport.
141+
```
142+
143+
### `formula`
144+
145+
- LaTeX math expression (without delimiters)
146+
- Use standard notation consistent with references
147+
- Include defining equations for derived quantities
148+
149+
### `reference`
150+
151+
- Free-form string for citation
152+
- Preferred format: `"Author, Journal Volume, Pages (Year)"`
153+
- For internal standards: `"openPMD-beamphysics standard"`
154+
155+
### `reference_url`
156+
157+
- Full URL (preferably DOI link)
158+
- Format: `"https://doi.org/10.xxxx/xxxxx"`
159+
160+
## Example Entry
161+
162+
```yaml
163+
- label: norm_emit_x
164+
mathlabel: \epsilon_{n,x}
165+
units: m
166+
description: >-
167+
Normalized RMS emittance in the horizontal plane.
168+
Invariant under linear transport for a relativistic beam.
169+
formula: \epsilon_{n,x} = \frac{1}{mc} \sqrt{\langle x^2 \rangle \langle p_x^2 \rangle - \langle x p_x \rangle^2}
170+
reference: "Wiedemann, Particle Accelerator Physics (Springer)"
171+
reference_url: https://doi.org/10.1007/978-3-319-18317-6
172+
category: emittance
173+
```
174+
175+
## Adding New Statistics
176+
177+
To add a new statistic:
178+
179+
1. Identify the appropriate category (or create a new one if needed)
180+
2. Add an entry to the `statistics` list with all required fields
181+
3. Include `formula` if the quantity is derived from other quantities
182+
4. Add `reference_url` if a DOI or stable URL is available
183+
5. Run the validation script to check for errors:
184+
```bash
185+
python scripts/generate_statistics_docs.py --validate
186+
```
187+
6. Regenerate the documentation:
188+
```bash
189+
python scripts/generate_statistics_docs.py
190+
```
191+
192+
## Computed Statistics
193+
194+
The `ParticleGroup` class supports computed statistics via bracket access with prefixes:
195+
196+
| Prefix | Example | Computes |
197+
|--------|---------|----------|
198+
| `sigma_` | `P['sigma_x']` | Standard deviation |
199+
| `mean_` | `P['mean_x']` | Weighted average |
200+
| `min_` | `P['min_x']` | Minimum value |
201+
| `max_` | `P['max_x']` | Maximum value |
202+
| `ptp_` | `P['ptp_x']` | Peak-to-peak (max - min) |
203+
| `delta_` | `P['delta_x']` | Value minus mean |
204+
| `cov_X__Y` | `P['cov_x__px']` | Covariance element |
205+
206+
These derived quantities do not need individual entries in the YAML file, as their units and labels are computed automatically from the base quantity.
207+
208+
## Integration with Code
209+
210+
The statistics standard YAML file can be loaded and used programmatically:
211+
212+
```python
213+
import yaml
214+
from pathlib import Path
215+
216+
# Load the standard
217+
yaml_path = Path(__file__).parent / "statistics_standard.yaml"
218+
with open(yaml_path) as f:
219+
standard = yaml.safe_load(f)
220+
221+
# Access statistics
222+
for stat in standard['statistics']:
223+
print(f"{stat['label']}: {stat['units']}")
224+
```

‎environment.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ dependencies:
1313
- pytest
1414
- pytest-benchmark
1515
- pytest-cov
16+
- pyyaml
1617
- jupyterlab>=3
1718
- nbconvert
1819
# Documentation

‎mkdocs.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,13 @@ nav:
3636
- Fields: api/fields.md
3737
- Wakefields: api/wakefields.md
3838

39+
- Standards:
40+
- Statistics Standard: api/statistics_standard.md
41+
- Computed Statistics: api/computed_statistics.md
42+
43+
- Contributing:
44+
- Statistics Schema: statistics_schema.md
45+
3946
theme:
4047
icon:
4148
repo: fontawesome/brands/github
@@ -62,6 +69,7 @@ theme:
6269
name: Switch to light mode
6370

6471
markdown_extensions:
72+
- attr_list
6573
- pymdownx.highlight
6674
- pymdownx.superfences
6775
- pymdownx.arithmatex: # Enable MathJAX https://squidfunk.github.io/mkdocs-material/reference/mathjax/

‎pmd_beamphysics/standards/__init__.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
"""
2+
Standards module for openPMD-beamphysics.
3+
4+
This module provides YAML-based standards for beam physics quantities.
5+
6+
Submodules:
7+
statistics: Particle beam statistics standard
8+
"""
9+
10+
from . import statistics
11+
12+
__all__ = ["statistics"]

0 commit comments

Comments
 (0)