pals2cosy 0.4.0__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.
@@ -0,0 +1,178 @@
1
+ Metadata-Version: 2.4
2
+ Name: pals2cosy
3
+ Version: 0.4.0
4
+ Summary: Convert PALS lattice files to COSY INFINITY FOX code
5
+ Author-email: Eremey Valetov <valetov@hawaii.edu>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/evvaletov/pals2cosy
8
+ Project-URL: Repository, https://github.com/evvaletov/pals2cosy
9
+ Keywords: beam-physics,accelerator,COSY-INFINITY,PALS,lattice,transfer-map
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Scientific/Engineering :: Physics
19
+ Requires-Python: >=3.9
20
+ Description-Content-Type: text/markdown
21
+ Requires-Dist: pyyaml
22
+ Provides-Extra: toml
23
+ Requires-Dist: tomli; python_version < "3.11" and extra == "toml"
24
+ Provides-Extra: dev
25
+ Requires-Dist: pytest; extra == "dev"
26
+
27
+ # pals2cosy
28
+
29
+ Convert [PALS](https://pals-project.readthedocs.io/) lattice files to
30
+ [COSY INFINITY](https://cosyinfinity.org) FOX code.
31
+
32
+ Supports the **official PALS format** (`PALS:` root with `facility:`/`line:`
33
+ composition) with auto-detection from the root key. Also accepts a flat
34
+ `beamline:` format with positioned elements.
35
+
36
+ ## Installation
37
+
38
+ ```bash
39
+ pip install pals2cosy
40
+ ```
41
+
42
+ Or for development:
43
+
44
+ ```bash
45
+ pip install -e .
46
+ ```
47
+
48
+ Requires Python 3.9+ and PyYAML (for YAML input).
49
+
50
+ ## Usage
51
+
52
+ ```bash
53
+ # PALS FODO cell (auto-detected from PALS: root key)
54
+ pals2cosy examples/fodo.pals.yaml --ke 1000 --particle proton
55
+
56
+ # Write to file with fringe fields
57
+ pals2cosy beamline.pals.yaml -o output.fox --ke 40 --fr 1
58
+
59
+ # Select a specific BeamLine from the facility
60
+ pals2cosy lattice.pals.yaml --beamline fodo_cell --ke 1000
61
+
62
+ # Compute Twiss parameters (periodic lattices only)
63
+ pals2cosy lattice.pals.yaml --ke 1000 --particle proton --twiss
64
+ ```
65
+
66
+ ### Options
67
+
68
+ | Flag | Default | Description |
69
+ |------|---------|-------------|
70
+ | `-o FILE` | stdout | Output FOX file |
71
+ | `--ke FLOAT` | from lattice | Kinetic energy (MeV) |
72
+ | `--fr INT` | 0 | Fringe field order (0=none, 1=Enge, 2=symplectic, 3=high-precision Enge) |
73
+ | `--order INT` | 3 | DA computation order |
74
+ | `--dim INT` | 3 | Phase-space dimensions (2 or 3) |
75
+ | `--quad-aperture FLOAT` | 0.027 | Quadrupole bore diameter (m) |
76
+ | `--particle STR` | from lattice | Particle type (see [Supported particles](#supported-particles)) |
77
+ | `--twiss` | off | Append GT Twiss extraction (requires periodic lattice) |
78
+ | `--mode STR` | auto | Input format override |
79
+ | `--beamline NAME` | last | BeamLine to expand (official PALS only) |
80
+ | `--no-comments` | off | Omit element name comments in FOX output |
81
+
82
+ ## Input format
83
+
84
+ ```yaml
85
+ PALS:
86
+ version: null
87
+ facility:
88
+ - q1:
89
+ kind: Quadrupole
90
+ length: 1.0
91
+ MagneticMultipoleP:
92
+ Bn1: 1.0 # Pole-tip field (Tesla)
93
+ - b1:
94
+ kind: SBend
95
+ length: 2.0
96
+ BendP:
97
+ g_ref: 0.5 # Bend strength (1/m)
98
+ e1: 0.1 # Entrance edge angle (radians)
99
+ e2: 0.2 # Exit edge angle (radians)
100
+ - my_line:
101
+ kind: BeamLine
102
+ line:
103
+ - q1
104
+ - b1
105
+ ```
106
+
107
+ See `examples/fodo.pals.yaml` for a complete FODO cell with `inherit:` and `repeat:`.
108
+
109
+ ## Element mapping
110
+
111
+ | Input type | FOX command | Notes |
112
+ |-----------|-------------|-------|
113
+ | Quadrupole (Bn1) | `MQ L Bn1 r ;` | Direct pole-tip field |
114
+ | Quadrupole (current) | `MQ L {±G·I·r} r ;` | Sign from polarity |
115
+ | Sextupole (Bn2) | `MH L Bn2 r ;` | Drift if Bn2 absent |
116
+ | Octupole (Bn3) | `MO L Bn3 r ;` | Drift if Bn3 absent |
117
+ | Multipole (Bn1–Bn5) | `M5 L BQ BH BO BD BZ r ;` | Up to dodecapole; drift if all absent |
118
+ | Solenoid (Bz) | `CMS Bz D L ;` | Drift if Bz absent |
119
+ | RFCavity | `RF V 0 W PHI D ;` | Drift if voltage/frequency absent |
120
+ | Wiggler/Undulator | `WI B K L D 0 0 0 ;` | Drift if field/period absent |
121
+ | SBend/RBend (no Enge) | `DIL L θ g/2 e₁ 0 e₂ 0 ;` | |
122
+ | SBend/RBend (with Enge) | `FC ..; DIL ..; FD ;` | |
123
+ | SBend (negative angle) | `CB ; DIL ..; CB ;` | |
124
+ | BPM/OTR/Corrector | _(skipped)_ | Zero-length |
125
+
126
+ ## Supported particles
127
+
128
+ | Name | FOX command | Notes |
129
+ |------|------------|-------|
130
+ | `electron` | `RPE` | Preset |
131
+ | `proton` | `RPP` | Preset |
132
+ | `muon`, `mu-` | `RPMU` | μ⁻ preset |
133
+ | `mu+`, `antimuon` | `RP` | μ⁺ via generic RP (RPMU hardcodes charge −1) |
134
+ | `pion+`, `pi+` | `RPPI E 1` | Preset with charge |
135
+ | `pion-`, `pi-` | `RPPI E -1` | Preset with charge |
136
+ | `positron` | `RP` | Generic |
137
+ | `antiproton` | `RP` | Generic |
138
+ | `deuteron` | `RP` | Generic |
139
+ | `alpha` | `RP` | Generic (⁴He²⁺) |
140
+ | `carbon12` | `RP` | Generic (¹²C⁶⁺) |
141
+
142
+ ## Known limitations
143
+
144
+ - **Drift fallback:** All active elements fall back to drifts when their field
145
+ parameters are absent.
146
+ - **Enge coefficients:** Maximum 6 coefficients per fringe field (COSY INFINITY FC
147
+ command limit). Longer coefficient lists are truncated with a warning.
148
+ - **Quad sign convention:** The current-based quadrupole path (`±G·I·r`) uses an
149
+ electron-specific sign convention (QPF→negative B, QPD→positive B). Proton beamlines
150
+ should use Bn1 (pole-tip field) instead, which bypasses the sign logic.
151
+
152
+ ## Roadmap
153
+
154
+ pals2cosy implements provisional support for element types and parameters that
155
+ are present in COSY INFINITY but not yet part of the official PALS specification,
156
+ such as `MagneticMultipoleP.Bn2`–`Bn5`, `SolenoidP.Bz`, and `RFCavityP`. As a
157
+ documented PALS use case, these extensions may inform future PALS standardization.
158
+ If PALS adopts a different parameterization, pals2cosy can be adjusted accordingly.
159
+
160
+ Planned extensions:
161
+ - Combined-function magnets (dipole + multipole fields → COSY `MC`/`MS`)
162
+ - Electrostatic deflectors (`EC`, `ECL`, `ES`)
163
+ - Skew multipoles (`MMS`, `EMS`)
164
+ - Particle tracking (`SR` + `TR` + `PRAY`/`WRAY`)
165
+ - FIT optimization blocks
166
+
167
+ ## Acknowledgments
168
+
169
+ This work was supported in part by DOE EPSCoR Award DE-SC0025583. The converter
170
+ is based in part on research performed on the University of Hawaiʻi free electron
171
+ laser by the author.
172
+
173
+ ## Tests
174
+
175
+ ```bash
176
+ pip install pytest
177
+ pytest tests/ -v
178
+ ```
@@ -0,0 +1,152 @@
1
+ # pals2cosy
2
+
3
+ Convert [PALS](https://pals-project.readthedocs.io/) lattice files to
4
+ [COSY INFINITY](https://cosyinfinity.org) FOX code.
5
+
6
+ Supports the **official PALS format** (`PALS:` root with `facility:`/`line:`
7
+ composition) with auto-detection from the root key. Also accepts a flat
8
+ `beamline:` format with positioned elements.
9
+
10
+ ## Installation
11
+
12
+ ```bash
13
+ pip install pals2cosy
14
+ ```
15
+
16
+ Or for development:
17
+
18
+ ```bash
19
+ pip install -e .
20
+ ```
21
+
22
+ Requires Python 3.9+ and PyYAML (for YAML input).
23
+
24
+ ## Usage
25
+
26
+ ```bash
27
+ # PALS FODO cell (auto-detected from PALS: root key)
28
+ pals2cosy examples/fodo.pals.yaml --ke 1000 --particle proton
29
+
30
+ # Write to file with fringe fields
31
+ pals2cosy beamline.pals.yaml -o output.fox --ke 40 --fr 1
32
+
33
+ # Select a specific BeamLine from the facility
34
+ pals2cosy lattice.pals.yaml --beamline fodo_cell --ke 1000
35
+
36
+ # Compute Twiss parameters (periodic lattices only)
37
+ pals2cosy lattice.pals.yaml --ke 1000 --particle proton --twiss
38
+ ```
39
+
40
+ ### Options
41
+
42
+ | Flag | Default | Description |
43
+ |------|---------|-------------|
44
+ | `-o FILE` | stdout | Output FOX file |
45
+ | `--ke FLOAT` | from lattice | Kinetic energy (MeV) |
46
+ | `--fr INT` | 0 | Fringe field order (0=none, 1=Enge, 2=symplectic, 3=high-precision Enge) |
47
+ | `--order INT` | 3 | DA computation order |
48
+ | `--dim INT` | 3 | Phase-space dimensions (2 or 3) |
49
+ | `--quad-aperture FLOAT` | 0.027 | Quadrupole bore diameter (m) |
50
+ | `--particle STR` | from lattice | Particle type (see [Supported particles](#supported-particles)) |
51
+ | `--twiss` | off | Append GT Twiss extraction (requires periodic lattice) |
52
+ | `--mode STR` | auto | Input format override |
53
+ | `--beamline NAME` | last | BeamLine to expand (official PALS only) |
54
+ | `--no-comments` | off | Omit element name comments in FOX output |
55
+
56
+ ## Input format
57
+
58
+ ```yaml
59
+ PALS:
60
+ version: null
61
+ facility:
62
+ - q1:
63
+ kind: Quadrupole
64
+ length: 1.0
65
+ MagneticMultipoleP:
66
+ Bn1: 1.0 # Pole-tip field (Tesla)
67
+ - b1:
68
+ kind: SBend
69
+ length: 2.0
70
+ BendP:
71
+ g_ref: 0.5 # Bend strength (1/m)
72
+ e1: 0.1 # Entrance edge angle (radians)
73
+ e2: 0.2 # Exit edge angle (radians)
74
+ - my_line:
75
+ kind: BeamLine
76
+ line:
77
+ - q1
78
+ - b1
79
+ ```
80
+
81
+ See `examples/fodo.pals.yaml` for a complete FODO cell with `inherit:` and `repeat:`.
82
+
83
+ ## Element mapping
84
+
85
+ | Input type | FOX command | Notes |
86
+ |-----------|-------------|-------|
87
+ | Quadrupole (Bn1) | `MQ L Bn1 r ;` | Direct pole-tip field |
88
+ | Quadrupole (current) | `MQ L {±G·I·r} r ;` | Sign from polarity |
89
+ | Sextupole (Bn2) | `MH L Bn2 r ;` | Drift if Bn2 absent |
90
+ | Octupole (Bn3) | `MO L Bn3 r ;` | Drift if Bn3 absent |
91
+ | Multipole (Bn1–Bn5) | `M5 L BQ BH BO BD BZ r ;` | Up to dodecapole; drift if all absent |
92
+ | Solenoid (Bz) | `CMS Bz D L ;` | Drift if Bz absent |
93
+ | RFCavity | `RF V 0 W PHI D ;` | Drift if voltage/frequency absent |
94
+ | Wiggler/Undulator | `WI B K L D 0 0 0 ;` | Drift if field/period absent |
95
+ | SBend/RBend (no Enge) | `DIL L θ g/2 e₁ 0 e₂ 0 ;` | |
96
+ | SBend/RBend (with Enge) | `FC ..; DIL ..; FD ;` | |
97
+ | SBend (negative angle) | `CB ; DIL ..; CB ;` | |
98
+ | BPM/OTR/Corrector | _(skipped)_ | Zero-length |
99
+
100
+ ## Supported particles
101
+
102
+ | Name | FOX command | Notes |
103
+ |------|------------|-------|
104
+ | `electron` | `RPE` | Preset |
105
+ | `proton` | `RPP` | Preset |
106
+ | `muon`, `mu-` | `RPMU` | μ⁻ preset |
107
+ | `mu+`, `antimuon` | `RP` | μ⁺ via generic RP (RPMU hardcodes charge −1) |
108
+ | `pion+`, `pi+` | `RPPI E 1` | Preset with charge |
109
+ | `pion-`, `pi-` | `RPPI E -1` | Preset with charge |
110
+ | `positron` | `RP` | Generic |
111
+ | `antiproton` | `RP` | Generic |
112
+ | `deuteron` | `RP` | Generic |
113
+ | `alpha` | `RP` | Generic (⁴He²⁺) |
114
+ | `carbon12` | `RP` | Generic (¹²C⁶⁺) |
115
+
116
+ ## Known limitations
117
+
118
+ - **Drift fallback:** All active elements fall back to drifts when their field
119
+ parameters are absent.
120
+ - **Enge coefficients:** Maximum 6 coefficients per fringe field (COSY INFINITY FC
121
+ command limit). Longer coefficient lists are truncated with a warning.
122
+ - **Quad sign convention:** The current-based quadrupole path (`±G·I·r`) uses an
123
+ electron-specific sign convention (QPF→negative B, QPD→positive B). Proton beamlines
124
+ should use Bn1 (pole-tip field) instead, which bypasses the sign logic.
125
+
126
+ ## Roadmap
127
+
128
+ pals2cosy implements provisional support for element types and parameters that
129
+ are present in COSY INFINITY but not yet part of the official PALS specification,
130
+ such as `MagneticMultipoleP.Bn2`–`Bn5`, `SolenoidP.Bz`, and `RFCavityP`. As a
131
+ documented PALS use case, these extensions may inform future PALS standardization.
132
+ If PALS adopts a different parameterization, pals2cosy can be adjusted accordingly.
133
+
134
+ Planned extensions:
135
+ - Combined-function magnets (dipole + multipole fields → COSY `MC`/`MS`)
136
+ - Electrostatic deflectors (`EC`, `ECL`, `ES`)
137
+ - Skew multipoles (`MMS`, `EMS`)
138
+ - Particle tracking (`SR` + `TR` + `PRAY`/`WRAY`)
139
+ - FIT optimization blocks
140
+
141
+ ## Acknowledgments
142
+
143
+ This work was supported in part by DOE EPSCoR Award DE-SC0025583. The converter
144
+ is based in part on research performed on the University of Hawaiʻi free electron
145
+ laser by the author.
146
+
147
+ ## Tests
148
+
149
+ ```bash
150
+ pip install pytest
151
+ pytest tests/ -v
152
+ ```
@@ -0,0 +1,7 @@
1
+ """pals2cosy — PALS Lattice to COSY INFINITY FOX converter."""
2
+
3
+ __version__ = "0.4.0"
4
+
5
+ from .converter import convert
6
+ from .parser import parse_lattice
7
+ from .pals_parser import parse_lattice as parse_pals_lattice
@@ -0,0 +1,3 @@
1
+ from pals2cosy.cli import main
2
+
3
+ main()
@@ -0,0 +1,24 @@
1
+ """Shared file loading utilities for JSON, YAML, and TOML inputs.
2
+
3
+ Author: Eremey Valetov
4
+ """
5
+
6
+ import json
7
+ import os
8
+
9
+
10
+ def load_file(path):
11
+ """Load a JSON, YAML, or TOML file, auto-detecting from extension."""
12
+ ext = os.path.splitext(path)[1].lower()
13
+ if ext == ".toml":
14
+ try:
15
+ import tomllib
16
+ except ModuleNotFoundError:
17
+ import tomli as tomllib
18
+ with open(path, "rb") as f:
19
+ return tomllib.load(f)
20
+ with open(path, "r") as f:
21
+ if ext in (".yaml", ".yml"):
22
+ import yaml
23
+ return yaml.safe_load(f)
24
+ return json.load(f)
@@ -0,0 +1,125 @@
1
+ """Command-line interface for pals2cosy.
2
+
3
+ Author: Eremey Valetov
4
+ """
5
+
6
+ import argparse
7
+ import json
8
+ import sys
9
+ import warnings
10
+
11
+ from ._io import load_file
12
+ from .converter import convert
13
+
14
+
15
+ def _detect_format(path):
16
+ """Auto-detect input format from root key.
17
+
18
+ Returns ``"official-pals"`` if root key is ``PALS:``,
19
+ ``"felsim"`` if root key is ``beamline:``.
20
+ """
21
+ try:
22
+ data = load_file(path)
23
+ except (json.JSONDecodeError, ValueError) as e:
24
+ raise ValueError(f"Cannot parse '{path}': {e}") from e
25
+ except Exception as e:
26
+ # Catch YAML parse errors (yaml.YAMLError) and other format-specific
27
+ # exceptions without importing yaml at module level
28
+ if type(e).__module__.startswith("yaml"):
29
+ raise ValueError(f"Cannot parse '{path}': {e}") from e
30
+ raise
31
+
32
+ if not isinstance(data, dict):
33
+ raise ValueError(
34
+ f"Cannot auto-detect format for '{path}': "
35
+ f"expected a mapping at top level, got {type(data).__name__}"
36
+ )
37
+
38
+ if "PALS" in data:
39
+ return "official-pals"
40
+ if "beamline" in data:
41
+ return "felsim"
42
+
43
+ raise ValueError(
44
+ f"Cannot auto-detect format for '{path}'. "
45
+ "Expected root key 'PALS:' (official PALS) or 'beamline:' (flat format)."
46
+ )
47
+
48
+
49
+ def main():
50
+ parser = argparse.ArgumentParser(
51
+ prog="pals2cosy",
52
+ description="Convert a PALS lattice (JSON/YAML) to COSY INFINITY FOX code.",
53
+ )
54
+ parser.add_argument("input", help="Input lattice file (JSON or YAML)")
55
+ parser.add_argument("-o", "--output", help="Output FOX file (default: stdout)")
56
+ parser.add_argument("--fr", type=int, default=0, help="Fringe field order (default: 0)")
57
+ parser.add_argument("--order", type=int, default=3, help="DA computation order (default: 3)")
58
+ parser.add_argument("--dim", type=int, default=3, choices=[2, 3],
59
+ help="Phase-space dimensions (default: 3)")
60
+ parser.add_argument("--ke", type=float, default=None,
61
+ help="Override kinetic energy (MeV)")
62
+ parser.add_argument("--particle", type=str, default=None,
63
+ help="Override particle type. Presets: electron, proton, muon/mu-, "
64
+ "pion+/pi+, pion-/pi-. Generic RP: mu+/antimuon, positron, "
65
+ "antiproton, deuteron, alpha, carbon12")
66
+ parser.add_argument("--quad-aperture", type=float, default=0.027,
67
+ help="Quadrupole bore diameter in meters (default: 0.027)")
68
+ parser.add_argument("--no-comments", action="store_true",
69
+ help="Omit element name comments")
70
+ parser.add_argument("--twiss", action="store_true",
71
+ help="Append GT Twiss extraction and JSON output (requires periodic lattice)")
72
+ parser.add_argument("--mode", type=str, default="auto",
73
+ choices=["auto", "felsim", "felsim-strict", "pals", "official-pals"],
74
+ help="Input format override (default: auto)")
75
+ parser.add_argument("--beamline", type=str, default=None,
76
+ help="BeamLine name to expand (official PALS only; default: last)")
77
+
78
+ args = parser.parse_args()
79
+
80
+ mode = args.mode
81
+ if mode == "auto":
82
+ mode = _detect_format(args.input)
83
+ if mode == "pals":
84
+ warnings.warn(
85
+ "--mode pals is deprecated; use --mode felsim-strict instead",
86
+ DeprecationWarning,
87
+ stacklevel=2,
88
+ )
89
+ if mode == "felsim-strict":
90
+ mode = "pals" # internal name for FELsim strict mode
91
+
92
+ if mode == "official-pals":
93
+ from .pals_parser import parse_lattice as parse_pals
94
+ beam_params, elements = parse_pals(
95
+ args.input,
96
+ beamline_name=args.beamline,
97
+ ke_override=args.ke,
98
+ particle_override=args.particle,
99
+ )
100
+ else:
101
+ if args.beamline is not None:
102
+ warnings.warn(
103
+ f"--beamline is only used with official-pals mode; "
104
+ f"ignored for mode '{mode}'"
105
+ )
106
+ from .parser import parse_lattice
107
+ beam_params, elements = parse_lattice(args.input, mode=mode)
108
+
109
+ fox = convert(
110
+ beam_params, elements,
111
+ fringe_field_order=args.fr,
112
+ computation_order=args.order,
113
+ dimensions=args.dim,
114
+ quad_aperture=args.quad_aperture,
115
+ ke_override=args.ke,
116
+ particle_override=args.particle,
117
+ comments=not args.no_comments,
118
+ twiss=args.twiss,
119
+ )
120
+
121
+ if args.output:
122
+ with open(args.output, "w") as f:
123
+ f.write(fox)
124
+ else:
125
+ sys.stdout.write(fox)
@@ -0,0 +1,9 @@
1
+ """Physical constants for beam physics (CODATA 2018 values).
2
+
3
+ Author: Eremey Valetov
4
+ """
5
+
6
+ E0_ELECTRON = 0.51099895000 # MeV
7
+ E0_PROTON = 938.27208816 # MeV
8
+ G_QUAD_DEFAULT = 2.694 # T/A/m
9
+ F_RF_DEFAULT = 2856e6 # Hz