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.
Files changed (38) hide show
  1. pymadng_utils-0.0.1/LICENSE +21 -0
  2. pymadng_utils-0.0.1/MANIFEST.in +1 -0
  3. pymadng_utils-0.0.1/PKG-INFO +170 -0
  4. pymadng_utils-0.0.1/README.md +128 -0
  5. pymadng_utils-0.0.1/pyproject.toml +94 -0
  6. pymadng_utils-0.0.1/setup.cfg +4 -0
  7. pymadng_utils-0.0.1/src/pymadng_utils/__init__.py +22 -0
  8. pymadng_utils-0.0.1/src/pymadng_utils/accelerators/__init__.py +16 -0
  9. pymadng_utils-0.0.1/src/pymadng_utils/accelerators/base.py +113 -0
  10. pymadng_utils-0.0.1/src/pymadng_utils/accelerators/fcc.py +108 -0
  11. pymadng_utils-0.0.1/src/pymadng_utils/accelerators/lhc.py +115 -0
  12. pymadng_utils-0.0.1/src/pymadng_utils/accelerators/psb.py +79 -0
  13. pymadng_utils-0.0.1/src/pymadng_utils/config.py +8 -0
  14. pymadng_utils-0.0.1/src/pymadng_utils/io/__init__.py +8 -0
  15. pymadng_utils-0.0.1/src/pymadng_utils/io/utils.py +49 -0
  16. pymadng_utils-0.0.1/src/pymadng_utils/mad/__init__.py +13 -0
  17. pymadng_utils-0.0.1/src/pymadng_utils/mad/ac_kickers.py +87 -0
  18. pymadng_utils-0.0.1/src/pymadng_utils/mad/accelerator_mad_interface.py +1076 -0
  19. pymadng_utils-0.0.1/src/pymadng_utils/mad/knob_mad_interface.py +153 -0
  20. pymadng_utils-0.0.1/src/pymadng_utils/mad/model_creator_mad_interface.py +161 -0
  21. pymadng_utils-0.0.1/src/pymadng_utils/mad_scripts/match_tunes.mad +30 -0
  22. pymadng_utils-0.0.1/src/pymadng_utils/mad_scripts/shush_mad_output.mad +43 -0
  23. pymadng_utils-0.0.1/src/pymadng_utils/madx/__init__.py +13 -0
  24. pymadng_utils-0.0.1/src/pymadng_utils/madx/constants.py +19 -0
  25. pymadng_utils-0.0.1/src/pymadng_utils/madx/make_sequence.py +295 -0
  26. pymadng_utils-0.0.1/src/pymadng_utils/madx/tfs_utils.py +98 -0
  27. pymadng_utils-0.0.1/src/pymadng_utils/model_creator/__init__.py +3 -0
  28. pymadng_utils-0.0.1/src/pymadng_utils/model_creator/constants.py +86 -0
  29. pymadng_utils-0.0.1/src/pymadng_utils/model_creator/create_fcc_model.py +82 -0
  30. pymadng_utils-0.0.1/src/pymadng_utils/model_creator/create_models.py +252 -0
  31. pymadng_utils-0.0.1/src/pymadng_utils/model_creator/madng_utils.py +71 -0
  32. pymadng_utils-0.0.1/src/pymadng_utils/physics.py +94 -0
  33. pymadng_utils-0.0.1/src/pymadng_utils/py.typed +0 -0
  34. pymadng_utils-0.0.1/src/pymadng_utils.egg-info/PKG-INFO +170 -0
  35. pymadng_utils-0.0.1/src/pymadng_utils.egg-info/SOURCES.txt +36 -0
  36. pymadng_utils-0.0.1/src/pymadng_utils.egg-info/dependency_links.txt +1 -0
  37. pymadng_utils-0.0.1/src/pymadng_utils.egg-info/requires.txt +22 -0
  38. 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
+ [![codecov](https://codecov.io/gh/jgray-19/pymadng-utils/graph/badge.svg?token=L1EV8MDM6M)](https://codecov.io/gh/jgray-19/pymadng-utils)
46
+ [![Coverage](https://github.com/jgray-19/pymadng-utils/actions/workflows/coverage.yml/badge.svg)](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
+ [![codecov](https://codecov.io/gh/jgray-19/pymadng-utils/graph/badge.svg?token=L1EV8MDM6M)](https://codecov.io/gh/jgray-19/pymadng-utils)
4
+ [![Coverage](https://github.com/jgray-19/pymadng-utils/actions/workflows/coverage.yml/badge.svg)](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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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)."""