pymadng-utils 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pymadng_utils-0.0.1/LICENSE +21 -0
- pymadng_utils-0.0.1/MANIFEST.in +1 -0
- pymadng_utils-0.0.1/PKG-INFO +170 -0
- pymadng_utils-0.0.1/README.md +128 -0
- pymadng_utils-0.0.1/pyproject.toml +94 -0
- pymadng_utils-0.0.1/setup.cfg +4 -0
- pymadng_utils-0.0.1/src/pymadng_utils/__init__.py +22 -0
- pymadng_utils-0.0.1/src/pymadng_utils/accelerators/__init__.py +16 -0
- pymadng_utils-0.0.1/src/pymadng_utils/accelerators/base.py +113 -0
- pymadng_utils-0.0.1/src/pymadng_utils/accelerators/fcc.py +108 -0
- pymadng_utils-0.0.1/src/pymadng_utils/accelerators/lhc.py +115 -0
- pymadng_utils-0.0.1/src/pymadng_utils/accelerators/psb.py +79 -0
- pymadng_utils-0.0.1/src/pymadng_utils/config.py +8 -0
- pymadng_utils-0.0.1/src/pymadng_utils/io/__init__.py +8 -0
- pymadng_utils-0.0.1/src/pymadng_utils/io/utils.py +49 -0
- pymadng_utils-0.0.1/src/pymadng_utils/mad/__init__.py +13 -0
- pymadng_utils-0.0.1/src/pymadng_utils/mad/ac_kickers.py +87 -0
- pymadng_utils-0.0.1/src/pymadng_utils/mad/accelerator_mad_interface.py +1076 -0
- pymadng_utils-0.0.1/src/pymadng_utils/mad/knob_mad_interface.py +153 -0
- pymadng_utils-0.0.1/src/pymadng_utils/mad/model_creator_mad_interface.py +161 -0
- pymadng_utils-0.0.1/src/pymadng_utils/mad_scripts/match_tunes.mad +30 -0
- pymadng_utils-0.0.1/src/pymadng_utils/mad_scripts/shush_mad_output.mad +43 -0
- pymadng_utils-0.0.1/src/pymadng_utils/madx/__init__.py +13 -0
- pymadng_utils-0.0.1/src/pymadng_utils/madx/constants.py +19 -0
- pymadng_utils-0.0.1/src/pymadng_utils/madx/make_sequence.py +295 -0
- pymadng_utils-0.0.1/src/pymadng_utils/madx/tfs_utils.py +98 -0
- pymadng_utils-0.0.1/src/pymadng_utils/model_creator/__init__.py +3 -0
- pymadng_utils-0.0.1/src/pymadng_utils/model_creator/constants.py +86 -0
- pymadng_utils-0.0.1/src/pymadng_utils/model_creator/create_fcc_model.py +82 -0
- pymadng_utils-0.0.1/src/pymadng_utils/model_creator/create_models.py +252 -0
- pymadng_utils-0.0.1/src/pymadng_utils/model_creator/madng_utils.py +71 -0
- pymadng_utils-0.0.1/src/pymadng_utils/physics.py +94 -0
- pymadng_utils-0.0.1/src/pymadng_utils/py.typed +0 -0
- pymadng_utils-0.0.1/src/pymadng_utils.egg-info/PKG-INFO +170 -0
- pymadng_utils-0.0.1/src/pymadng_utils.egg-info/SOURCES.txt +36 -0
- pymadng_utils-0.0.1/src/pymadng_utils.egg-info/dependency_links.txt +1 -0
- pymadng_utils-0.0.1/src/pymadng_utils.egg-info/requires.txt +22 -0
- pymadng_utils-0.0.1/src/pymadng_utils.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Joshua Gray
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
prune tests
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pymadng-utils
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: MAD-NG and pymadng utility interfaces and tests
|
|
5
|
+
Author: Joshua Gray
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Repository, https://github.com/jgray-19/pymadng-utils
|
|
8
|
+
Project-URL: Documentation, https://jgray-19.github.io/pymadng-utils/
|
|
9
|
+
Project-URL: Issues, https://github.com/jgray-19/pymadng-utils/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/jgray-19/pymadng-utils/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: MAD-NG,MAD-X,accelerator,optics,LHC,PSB,FCC-ee
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Operating System :: POSIX
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: numpy
|
|
24
|
+
Requires-Dist: pandas
|
|
25
|
+
Requires-Dist: tfs-pandas
|
|
26
|
+
Requires-Dist: pymadng>=0.10.0
|
|
27
|
+
Provides-Extra: test
|
|
28
|
+
Requires-Dist: pytest; extra == "test"
|
|
29
|
+
Requires-Dist: pytest-cov; extra == "test"
|
|
30
|
+
Requires-Dist: cpymad; extra == "test"
|
|
31
|
+
Requires-Dist: omc3; extra == "test"
|
|
32
|
+
Provides-Extra: model
|
|
33
|
+
Requires-Dist: cpymad; extra == "model"
|
|
34
|
+
Requires-Dist: omc3; extra == "model"
|
|
35
|
+
Provides-Extra: dev
|
|
36
|
+
Requires-Dist: pre-commit<5,>=4; extra == "dev"
|
|
37
|
+
Requires-Dist: ruff<0.14,>=0.13; extra == "dev"
|
|
38
|
+
Provides-Extra: docs
|
|
39
|
+
Requires-Dist: sphinx>=8; extra == "docs"
|
|
40
|
+
Requires-Dist: furo>=2025.12.19; extra == "docs"
|
|
41
|
+
Dynamic: license-file
|
|
42
|
+
|
|
43
|
+
# pymadng-utils
|
|
44
|
+
|
|
45
|
+
[](https://codecov.io/gh/jgray-19/pymadng-utils)
|
|
46
|
+
[](https://github.com/jgray-19/pymadng-utils/actions/workflows/coverage.yml)
|
|
47
|
+
|
|
48
|
+
> **Alpha (0.0.1).** The API may change without notice.
|
|
49
|
+
|
|
50
|
+
`pymadng-utils` is a small Python library for accelerator-model workflows that cross the MAD-X/MAD-NG boundary. It provides:
|
|
51
|
+
|
|
52
|
+
- LHC, PSB and FCC-ee machine descriptors;
|
|
53
|
+
- a managed MAD-NG session that loads a saved MAD-X sequence and configures its beam;
|
|
54
|
+
- observation, TWISS, tune matching, AC-dipole, AC-kicker, orbit-correction, magnet-strength, and perturbation helpers;
|
|
55
|
+
- conversion of MAD-NG TFS tables to MAD-X/OMC3 naming conventions;
|
|
56
|
+
- export of reusable sequences from existing OMC3 model directories; and
|
|
57
|
+
- end-to-end LHC and PSB model-creation workflows and FCC-ee lattice preparation.
|
|
58
|
+
|
|
59
|
+
The package is workflow infrastructure, not a replacement for MAD-NG, MAD-X, or OMC3. Most operations require a working accelerator software environment and real sequence/model files.
|
|
60
|
+
|
|
61
|
+
## Installation
|
|
62
|
+
|
|
63
|
+
Python 3.11 or newer is required.
|
|
64
|
+
|
|
65
|
+
Install the core package:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
python -m pip install .
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Install an editable checkout with the dependencies used by model creation and tests:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
python -m pip install -e '.[test]'
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The extras are:
|
|
78
|
+
|
|
79
|
+
| Extra | Adds | Intended use |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| `model` | `cpymad`, `omc3` | sequence export and model creation |
|
|
82
|
+
| `test` | `pytest`, `pytest-cov`, `cpymad`, `omc3` | repository test suite |
|
|
83
|
+
| `dev` | `pre-commit`, `ruff` | linting and pre-commit hooks |
|
|
84
|
+
| `docs` | Sphinx and the Furo theme | local documentation build |
|
|
85
|
+
|
|
86
|
+
MAD-NG itself must be usable by `pymadng`; `cpymad` additionally needs a working MAD-X installation. OMC3 model creation may also require access to CERN accelerator-model repositories, depending on its `fetch` configuration.
|
|
87
|
+
|
|
88
|
+
## Quick start: load a sequence and run TWISS
|
|
89
|
+
|
|
90
|
+
An accelerator descriptor holds the machine-specific contract: sequence name, particle and kinetic energy, BPM selection pattern, tune knobs, integer tunes, and AC-dipole element name. Constructing `AcceleratorMadInterface` immediately starts MAD-NG, loads the sequence, and attaches the beam.
|
|
91
|
+
|
|
92
|
+
```python
|
|
93
|
+
from pathlib import Path
|
|
94
|
+
|
|
95
|
+
from pymadng_utils.accelerators import LHC
|
|
96
|
+
from pymadng_utils.mad import AcceleratorMadInterface
|
|
97
|
+
|
|
98
|
+
accelerator = LHC(
|
|
99
|
+
beam=1,
|
|
100
|
+
sequence_file=Path("lhcb1_saved.seq"),
|
|
101
|
+
kinetic_energy=6800.0, # GeV; this is kinetic, not total energy
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
with AcceleratorMadInterface(accelerator) as interface:
|
|
105
|
+
interface.observe() # uses the LHC BPM pattern
|
|
106
|
+
twiss = interface.run_twiss(coupling=True)
|
|
107
|
+
print(twiss.headers["q1"], twiss.headers["q2"])
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`run_twiss()` returns the `pymadng` table converted to a DataFrame, indexed by element name when the result contains a `name` column. Its headers are augmented with `particle` and total `energy` in GeV.
|
|
111
|
+
|
|
112
|
+
Use the interface as a context manager, or call `close()` explicitly. The MAD-X sequence is translated on every load; `load_sequence(cache_translation=True)` writes a sibling `.mad` cache, which makes that directory writable-required and is unsafe for parallel loaders of the same sequence.
|
|
113
|
+
|
|
114
|
+
### Off-momentum coordinates
|
|
115
|
+
|
|
116
|
+
MAD-NG uses `pt`, while many accelerator workflows use relative momentum deviation `dp/p`. The descriptor and interface both expose beam-aware conversions:
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
with AcceleratorMadInterface(accelerator) as interface:
|
|
120
|
+
pt = interface.dp2pt(1e-3)
|
|
121
|
+
twiss = interface.run_twiss(pt=pt, coupling=True)
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
The convenience `pt=` argument is mutually exclusive with explicit `X0=` and `deltap=` arguments. A `deltap=` argument (without an explicit `X0=`) is normalised through the same path: it is converted to `pt` and seeded as the sixth `X0` coordinate, so `run_twiss(deltap=dp)`, `run_twiss(pt=interface.dp2pt(dp))`, and MAD-NG's own `twiss{deltap=dp}` are all bit-identical.
|
|
125
|
+
|
|
126
|
+
`interface.dp2pt`/`interface.pt2dp` run `MAD.gphys.dp2pt`/`pt2dp` inside MAD-NG on the loaded sequence's `beam.beta`, with the value sent and received over the pipe as a double, so nothing is lost to string formatting or to a second implementation of the same formula. Note these are not mutual inverses to the last bit (~1e-13 relative), and the closed-orbit search amplifies that to ~1e-9 on the orbit over a full ring, so convert once and stay in one coordinate rather than round-tripping. Standalone conversion functions are available from `pymadng_utils.physics` when the reference `beta` is already known and no MAD-NG session is at hand.
|
|
127
|
+
|
|
128
|
+
## What else is here
|
|
129
|
+
|
|
130
|
+
The [usage guide](https://github.com/jgray-19/pymadng-utils/blob/main/docs/usage.rst) documents the rest in full: the LHC and PSB
|
|
131
|
+
descriptors, the four MAD-NG interface classes and their operations, saved-sequence
|
|
132
|
+
export from an OMC3 model directory (LHC, PSB), model-table regeneration, the
|
|
133
|
+
packaged end-to-end LHC creator, and the TFS/knob conversion helpers. The
|
|
134
|
+
[API reference](https://github.com/jgray-19/pymadng-utils/blob/main/docs/api/index.rst) documents each object from its docstrings.
|
|
135
|
+
|
|
136
|
+
## Development
|
|
137
|
+
|
|
138
|
+
Install the git hooks once with `pre-commit install` (ruff, whitespace checks, and a commit-message check).
|
|
139
|
+
|
|
140
|
+
Run the test suite:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
pytest
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Some tests start MAD-NG or MAD-X and use committed accelerator fixtures; they are integration tests, not pure unit tests.
|
|
147
|
+
|
|
148
|
+
Build the Sphinx documentation:
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
python -m pip install -e '.[docs]'
|
|
152
|
+
make -C docs html
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
The generated site starts at `docs/_build/html/index.html`.
|
|
156
|
+
|
|
157
|
+
## Repository layout
|
|
158
|
+
|
|
159
|
+
```text
|
|
160
|
+
src/pymadng_utils/
|
|
161
|
+
├── accelerators/ LHC/PSB/FCC-ee descriptors
|
|
162
|
+
├── io/ knob-file I/O
|
|
163
|
+
├── mad/ MAD-NG session interfaces
|
|
164
|
+
├── mad_scripts/ packaged MAD-NG scripts (output suppression, tune matching)
|
|
165
|
+
├── madx/ sequence export and TFS conversion
|
|
166
|
+
├── model_creator/ higher-level model workflows
|
|
167
|
+
└── physics.py particle masses and dp/p ↔ pt conversion
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
The project is distributed under the terms in [`LICENSE`](https://github.com/jgray-19/pymadng-utils/blob/main/LICENSE).
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# pymadng-utils
|
|
2
|
+
|
|
3
|
+
[](https://codecov.io/gh/jgray-19/pymadng-utils)
|
|
4
|
+
[](https://github.com/jgray-19/pymadng-utils/actions/workflows/coverage.yml)
|
|
5
|
+
|
|
6
|
+
> **Alpha (0.0.1).** The API may change without notice.
|
|
7
|
+
|
|
8
|
+
`pymadng-utils` is a small Python library for accelerator-model workflows that cross the MAD-X/MAD-NG boundary. It provides:
|
|
9
|
+
|
|
10
|
+
- LHC, PSB and FCC-ee machine descriptors;
|
|
11
|
+
- a managed MAD-NG session that loads a saved MAD-X sequence and configures its beam;
|
|
12
|
+
- observation, TWISS, tune matching, AC-dipole, AC-kicker, orbit-correction, magnet-strength, and perturbation helpers;
|
|
13
|
+
- conversion of MAD-NG TFS tables to MAD-X/OMC3 naming conventions;
|
|
14
|
+
- export of reusable sequences from existing OMC3 model directories; and
|
|
15
|
+
- end-to-end LHC and PSB model-creation workflows and FCC-ee lattice preparation.
|
|
16
|
+
|
|
17
|
+
The package is workflow infrastructure, not a replacement for MAD-NG, MAD-X, or OMC3. Most operations require a working accelerator software environment and real sequence/model files.
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
Python 3.11 or newer is required.
|
|
22
|
+
|
|
23
|
+
Install the core package:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
python -m pip install .
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Install an editable checkout with the dependencies used by model creation and tests:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
python -m pip install -e '.[test]'
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The extras are:
|
|
36
|
+
|
|
37
|
+
| Extra | Adds | Intended use |
|
|
38
|
+
|---|---|---|
|
|
39
|
+
| `model` | `cpymad`, `omc3` | sequence export and model creation |
|
|
40
|
+
| `test` | `pytest`, `pytest-cov`, `cpymad`, `omc3` | repository test suite |
|
|
41
|
+
| `dev` | `pre-commit`, `ruff` | linting and pre-commit hooks |
|
|
42
|
+
| `docs` | Sphinx and the Furo theme | local documentation build |
|
|
43
|
+
|
|
44
|
+
MAD-NG itself must be usable by `pymadng`; `cpymad` additionally needs a working MAD-X installation. OMC3 model creation may also require access to CERN accelerator-model repositories, depending on its `fetch` configuration.
|
|
45
|
+
|
|
46
|
+
## Quick start: load a sequence and run TWISS
|
|
47
|
+
|
|
48
|
+
An accelerator descriptor holds the machine-specific contract: sequence name, particle and kinetic energy, BPM selection pattern, tune knobs, integer tunes, and AC-dipole element name. Constructing `AcceleratorMadInterface` immediately starts MAD-NG, loads the sequence, and attaches the beam.
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
from pathlib import Path
|
|
52
|
+
|
|
53
|
+
from pymadng_utils.accelerators import LHC
|
|
54
|
+
from pymadng_utils.mad import AcceleratorMadInterface
|
|
55
|
+
|
|
56
|
+
accelerator = LHC(
|
|
57
|
+
beam=1,
|
|
58
|
+
sequence_file=Path("lhcb1_saved.seq"),
|
|
59
|
+
kinetic_energy=6800.0, # GeV; this is kinetic, not total energy
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
with AcceleratorMadInterface(accelerator) as interface:
|
|
63
|
+
interface.observe() # uses the LHC BPM pattern
|
|
64
|
+
twiss = interface.run_twiss(coupling=True)
|
|
65
|
+
print(twiss.headers["q1"], twiss.headers["q2"])
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`run_twiss()` returns the `pymadng` table converted to a DataFrame, indexed by element name when the result contains a `name` column. Its headers are augmented with `particle` and total `energy` in GeV.
|
|
69
|
+
|
|
70
|
+
Use the interface as a context manager, or call `close()` explicitly. The MAD-X sequence is translated on every load; `load_sequence(cache_translation=True)` writes a sibling `.mad` cache, which makes that directory writable-required and is unsafe for parallel loaders of the same sequence.
|
|
71
|
+
|
|
72
|
+
### Off-momentum coordinates
|
|
73
|
+
|
|
74
|
+
MAD-NG uses `pt`, while many accelerator workflows use relative momentum deviation `dp/p`. The descriptor and interface both expose beam-aware conversions:
|
|
75
|
+
|
|
76
|
+
```python
|
|
77
|
+
with AcceleratorMadInterface(accelerator) as interface:
|
|
78
|
+
pt = interface.dp2pt(1e-3)
|
|
79
|
+
twiss = interface.run_twiss(pt=pt, coupling=True)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The convenience `pt=` argument is mutually exclusive with explicit `X0=` and `deltap=` arguments. A `deltap=` argument (without an explicit `X0=`) is normalised through the same path: it is converted to `pt` and seeded as the sixth `X0` coordinate, so `run_twiss(deltap=dp)`, `run_twiss(pt=interface.dp2pt(dp))`, and MAD-NG's own `twiss{deltap=dp}` are all bit-identical.
|
|
83
|
+
|
|
84
|
+
`interface.dp2pt`/`interface.pt2dp` run `MAD.gphys.dp2pt`/`pt2dp` inside MAD-NG on the loaded sequence's `beam.beta`, with the value sent and received over the pipe as a double, so nothing is lost to string formatting or to a second implementation of the same formula. Note these are not mutual inverses to the last bit (~1e-13 relative), and the closed-orbit search amplifies that to ~1e-9 on the orbit over a full ring, so convert once and stay in one coordinate rather than round-tripping. Standalone conversion functions are available from `pymadng_utils.physics` when the reference `beta` is already known and no MAD-NG session is at hand.
|
|
85
|
+
|
|
86
|
+
## What else is here
|
|
87
|
+
|
|
88
|
+
The [usage guide](https://github.com/jgray-19/pymadng-utils/blob/main/docs/usage.rst) documents the rest in full: the LHC and PSB
|
|
89
|
+
descriptors, the four MAD-NG interface classes and their operations, saved-sequence
|
|
90
|
+
export from an OMC3 model directory (LHC, PSB), model-table regeneration, the
|
|
91
|
+
packaged end-to-end LHC creator, and the TFS/knob conversion helpers. The
|
|
92
|
+
[API reference](https://github.com/jgray-19/pymadng-utils/blob/main/docs/api/index.rst) documents each object from its docstrings.
|
|
93
|
+
|
|
94
|
+
## Development
|
|
95
|
+
|
|
96
|
+
Install the git hooks once with `pre-commit install` (ruff, whitespace checks, and a commit-message check).
|
|
97
|
+
|
|
98
|
+
Run the test suite:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
pytest
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Some tests start MAD-NG or MAD-X and use committed accelerator fixtures; they are integration tests, not pure unit tests.
|
|
105
|
+
|
|
106
|
+
Build the Sphinx documentation:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
python -m pip install -e '.[docs]'
|
|
110
|
+
make -C docs html
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The generated site starts at `docs/_build/html/index.html`.
|
|
114
|
+
|
|
115
|
+
## Repository layout
|
|
116
|
+
|
|
117
|
+
```text
|
|
118
|
+
src/pymadng_utils/
|
|
119
|
+
├── accelerators/ LHC/PSB/FCC-ee descriptors
|
|
120
|
+
├── io/ knob-file I/O
|
|
121
|
+
├── mad/ MAD-NG session interfaces
|
|
122
|
+
├── mad_scripts/ packaged MAD-NG scripts (output suppression, tune matching)
|
|
123
|
+
├── madx/ sequence export and TFS conversion
|
|
124
|
+
├── model_creator/ higher-level model workflows
|
|
125
|
+
└── physics.py particle masses and dp/p ↔ pt conversion
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
The project is distributed under the terms in [`LICENSE`](https://github.com/jgray-19/pymadng-utils/blob/main/LICENSE).
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "pymadng-utils"
|
|
7
|
+
version = "0.0.1"
|
|
8
|
+
description = "MAD-NG and pymadng utility interfaces and tests"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
authors = [
|
|
11
|
+
{ name = "Joshua Gray" },
|
|
12
|
+
]
|
|
13
|
+
license = "MIT"
|
|
14
|
+
license-files = ["LICENSE"]
|
|
15
|
+
keywords = ["MAD-NG", "MAD-X", "accelerator", "optics", "LHC", "PSB", "FCC-ee"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 3 - Alpha",
|
|
18
|
+
"Intended Audience :: Science/Research",
|
|
19
|
+
"Operating System :: POSIX",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Topic :: Scientific/Engineering :: Physics",
|
|
25
|
+
]
|
|
26
|
+
requires-python = ">=3.11"
|
|
27
|
+
dependencies = [
|
|
28
|
+
"numpy",
|
|
29
|
+
"pandas",
|
|
30
|
+
"tfs-pandas",
|
|
31
|
+
"pymadng>=0.10.0",
|
|
32
|
+
]
|
|
33
|
+
|
|
34
|
+
[project.urls]
|
|
35
|
+
Repository = "https://github.com/jgray-19/pymadng-utils"
|
|
36
|
+
Documentation = "https://jgray-19.github.io/pymadng-utils/"
|
|
37
|
+
Issues = "https://github.com/jgray-19/pymadng-utils/issues"
|
|
38
|
+
Changelog = "https://github.com/jgray-19/pymadng-utils/blob/main/CHANGELOG.md"
|
|
39
|
+
|
|
40
|
+
[project.optional-dependencies]
|
|
41
|
+
test = [
|
|
42
|
+
"pytest",
|
|
43
|
+
"pytest-cov",
|
|
44
|
+
"cpymad",
|
|
45
|
+
"omc3",
|
|
46
|
+
]
|
|
47
|
+
model = [
|
|
48
|
+
"cpymad",
|
|
49
|
+
"omc3",
|
|
50
|
+
]
|
|
51
|
+
dev = [
|
|
52
|
+
"pre-commit>=4,<5",
|
|
53
|
+
"ruff>=0.13,<0.14",
|
|
54
|
+
]
|
|
55
|
+
docs = [
|
|
56
|
+
"sphinx>=8",
|
|
57
|
+
"furo>=2025.12.19",
|
|
58
|
+
]
|
|
59
|
+
|
|
60
|
+
[tool.setuptools]
|
|
61
|
+
package-dir = {"" = "src"}
|
|
62
|
+
|
|
63
|
+
[tool.setuptools.packages.find]
|
|
64
|
+
where = ["src"]
|
|
65
|
+
include = ["pymadng_utils*"]
|
|
66
|
+
|
|
67
|
+
[tool.setuptools.package-data]
|
|
68
|
+
pymadng_utils = ["mad_scripts/*.mad", "py.typed"]
|
|
69
|
+
|
|
70
|
+
[tool.pytest.ini_options]
|
|
71
|
+
testpaths = ["tests", "src/pymadng_utils/physics.py"]
|
|
72
|
+
norecursedirs = ["tests/data"]
|
|
73
|
+
addopts = [
|
|
74
|
+
"--doctest-modules",
|
|
75
|
+
"--log-cli-level=INFO",
|
|
76
|
+
"--log-level=INFO",
|
|
77
|
+
"--log-cli-format=%(levelname)s %(name)s %(message)s",
|
|
78
|
+
"-s",
|
|
79
|
+
]
|
|
80
|
+
|
|
81
|
+
[tool.coverage.run]
|
|
82
|
+
source = ["src"]
|
|
83
|
+
|
|
84
|
+
[tool.coverage.report]
|
|
85
|
+
omit = ["tests/*"]
|
|
86
|
+
|
|
87
|
+
[tool.ruff]
|
|
88
|
+
line-length = 100
|
|
89
|
+
target-version = "py311"
|
|
90
|
+
extend-exclude = ["tests/data", "build", "scratch_tmp"]
|
|
91
|
+
|
|
92
|
+
[tool.ruff.lint]
|
|
93
|
+
extend-select = ["I", "B", "UP", "RUF", "TC"]
|
|
94
|
+
ignore = ["E501"]
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"""Utilities for working with accelerator descriptors, MAD-NG, MAD-X, and model workflows."""
|
|
2
|
+
|
|
3
|
+
from importlib.metadata import version
|
|
4
|
+
|
|
5
|
+
from pymadng_utils.accelerators import FCC, LHC, PSB
|
|
6
|
+
from pymadng_utils.mad import (
|
|
7
|
+
AcceleratorErrorsMadInterface,
|
|
8
|
+
AcceleratorMadInterface,
|
|
9
|
+
KnobMadInterface,
|
|
10
|
+
)
|
|
11
|
+
|
|
12
|
+
__version__ = version("pymadng-utils")
|
|
13
|
+
|
|
14
|
+
__all__ = [
|
|
15
|
+
"FCC",
|
|
16
|
+
"LHC",
|
|
17
|
+
"PSB",
|
|
18
|
+
"AcceleratorErrorsMadInterface",
|
|
19
|
+
"AcceleratorMadInterface",
|
|
20
|
+
"KnobMadInterface",
|
|
21
|
+
"__version__",
|
|
22
|
+
]
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
"""Accelerator descriptors used by MAD-facing helpers."""
|
|
2
|
+
|
|
3
|
+
from pymadng_utils.accelerators.base import Accelerator
|
|
4
|
+
from pymadng_utils.accelerators.fcc import FCC
|
|
5
|
+
from pymadng_utils.accelerators.lhc import LHC
|
|
6
|
+
from pymadng_utils.accelerators.psb import PSB, PSB_FLAT_BOTTOM_GEV
|
|
7
|
+
from pymadng_utils.physics import PROTON_MASS_GEV
|
|
8
|
+
|
|
9
|
+
__all__ = [
|
|
10
|
+
"FCC",
|
|
11
|
+
"LHC",
|
|
12
|
+
"PROTON_MASS_GEV",
|
|
13
|
+
"PSB",
|
|
14
|
+
"PSB_FLAT_BOTTOM_GEV",
|
|
15
|
+
"Accelerator",
|
|
16
|
+
]
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"""Minimal accelerator definitions for MAD-facing helpers."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from abc import ABC, abstractmethod
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from pymadng_utils.physics import beta_from_energy, dp2pt, particle_mass, pt2dp
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class Accelerator(ABC):
|
|
13
|
+
"""Machine descriptor consumed by the MAD-NG interfaces.
|
|
14
|
+
|
|
15
|
+
Holds the sequence path, MAD sequence name, beam energy, BPM pattern, tune knobs and
|
|
16
|
+
integer tunes, and the AC-dipole element name.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
#: MAD-X ``rbarc`` option used when loading the sequence (rbend length is the straight chord if True).
|
|
20
|
+
RBARC = False
|
|
21
|
+
#: Set MAD-NG's ``option.nocharge`` before the beam is created.
|
|
22
|
+
NOCHARGE = False
|
|
23
|
+
#: MAD-NG ``sequence.dir``: -1 runs the loaded sequence backwards.
|
|
24
|
+
seq_dir = 1
|
|
25
|
+
|
|
26
|
+
def __init__(
|
|
27
|
+
self,
|
|
28
|
+
sequence_file: Path | str,
|
|
29
|
+
kinetic_energy: float,
|
|
30
|
+
bpm_pattern: str = "BPM",
|
|
31
|
+
particle: str = "proton",
|
|
32
|
+
**kwargs: Any,
|
|
33
|
+
) -> None:
|
|
34
|
+
if kwargs:
|
|
35
|
+
raise TypeError(f"Unexpected keyword arguments: {list(kwargs)}")
|
|
36
|
+
super().__init__()
|
|
37
|
+
self.sequence_file = Path(sequence_file)
|
|
38
|
+
self.kinetic_energy = float(kinetic_energy)
|
|
39
|
+
self.particle = str(particle)
|
|
40
|
+
self.energy = self.kinetic_energy + particle_mass(self.particle)
|
|
41
|
+
self.beta = beta_from_energy(self.energy, self.particle)
|
|
42
|
+
self.bpm_pattern = str(bpm_pattern)
|
|
43
|
+
|
|
44
|
+
def __repr__(self) -> str:
|
|
45
|
+
"""Return a developer-facing representation of public accelerator state."""
|
|
46
|
+
fields = ", ".join(
|
|
47
|
+
f"{name}={value!r}" for name, value in vars(self).items() if not name.startswith("_")
|
|
48
|
+
)
|
|
49
|
+
return f"{type(self).__name__}({fields})"
|
|
50
|
+
|
|
51
|
+
def __str__(self) -> str:
|
|
52
|
+
"""Return a concise human-readable accelerator summary."""
|
|
53
|
+
return (
|
|
54
|
+
f"{type(self).__name__}(seq_name={self.seq_name}, "
|
|
55
|
+
f"particle={self.particle}, "
|
|
56
|
+
f"kinetic_energy={self.kinetic_energy:g} GeV, "
|
|
57
|
+
f"sequence_file={self.sequence_file})"
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
def dp2pt(self, dp: float) -> float:
|
|
61
|
+
"""Convert relative momentum deviation ``dp/p`` to MAD-NG ``pt``."""
|
|
62
|
+
return dp2pt(dp, self.beta)
|
|
63
|
+
|
|
64
|
+
def pt2dp(self, pt: float) -> float:
|
|
65
|
+
"""Convert MAD-NG ``pt`` to relative momentum deviation ``dp/p``."""
|
|
66
|
+
return pt2dp(pt, self.beta)
|
|
67
|
+
|
|
68
|
+
@property
|
|
69
|
+
@abstractmethod
|
|
70
|
+
def seq_name(self) -> str:
|
|
71
|
+
"""Return the sequence name for this accelerator.
|
|
72
|
+
|
|
73
|
+
Returns:
|
|
74
|
+
Sequence name to use in MAD
|
|
75
|
+
"""
|
|
76
|
+
|
|
77
|
+
@property
|
|
78
|
+
@abstractmethod
|
|
79
|
+
def ac_dipole_name(self) -> str:
|
|
80
|
+
"""Return the name of the AC-dipole element."""
|
|
81
|
+
|
|
82
|
+
def acd_marker_name(self, side: str) -> str:
|
|
83
|
+
"""Return a stable row name for the AC-dipole marker state."""
|
|
84
|
+
if side not in {"before", "after"}:
|
|
85
|
+
raise ValueError(f"side must be 'before' or 'after', got {side!r}")
|
|
86
|
+
marker_name = self.ac_dipole_name
|
|
87
|
+
return f"{marker_name}_{side}"
|
|
88
|
+
|
|
89
|
+
def kicker_marker_name(self, kicker_name: str) -> str:
|
|
90
|
+
"""Return the measured initial-condition marker name for kicker tracking."""
|
|
91
|
+
return kicker_name
|
|
92
|
+
|
|
93
|
+
def kicker_cycle_marker_name(self, kicker_name: str) -> str:
|
|
94
|
+
"""Return the unobserved centre marker used to cycle kicker-mode tracking."""
|
|
95
|
+
return f"{kicker_name}_centre"
|
|
96
|
+
|
|
97
|
+
def apply_accelerator_specific_errors(self, mad_iface: Any) -> None:
|
|
98
|
+
"""Apply machine-specific startup errors to a loaded MAD sequence."""
|
|
99
|
+
del mad_iface
|
|
100
|
+
|
|
101
|
+
def get_perturbation_families(self) -> dict[str, dict[str, str | float | dict]]:
|
|
102
|
+
"""Return per-family perturbation metadata keyed by family code d/q/s."""
|
|
103
|
+
return {}
|
|
104
|
+
|
|
105
|
+
@property
|
|
106
|
+
@abstractmethod
|
|
107
|
+
def tune_variables(self) -> tuple[str, str]:
|
|
108
|
+
"""Return the MAD-X tune knob names (qx, qy)."""
|
|
109
|
+
|
|
110
|
+
@property
|
|
111
|
+
@abstractmethod
|
|
112
|
+
def tune_integers(self) -> tuple[int, int]:
|
|
113
|
+
"""Return the integer parts of the tunes (qx, qy)."""
|