Skip to content

Commit f16798b

Browse files
EZoniEZoni
committed
Update README.md
1 parent 5b7ee19 commit f16798b

File tree

1 file changed

+18
-176
lines changed

1 file changed

+18
-176
lines changed

‎README.md‎

Lines changed: 18 additions & 176 deletions
Original file line numberDiff line numberDiff line change
@@ -1,205 +1,47 @@
11
# Meet Your Python PALS
22

3-
This is a Python implementation for the Particle Accelerator Lattice Standard (PALS).
3+
This is a Python implementation for the Particle Accelerator Lattice Standard ([PALS](https://github.com/campa-consortium/pals)).
44

5-
To define the PALS schema, [Pydantic](https://docs.pydantic.dev) is used to map to Python objects, perform automatic validation, and to (de)serialize data classes to/from many modern file formats.
6-
Various modern file formats (e.g., YAML, JSON, TOML, XML, ...) are supported, which makes implementation of the schema-following creates files in any modern programming language easy (e.g., Python, Julia, LUA, C++, Javascript, ...).
5+
To define the PALS schema, [Pydantic](https://docs.pydantic.dev) is used to map to Python objects, perform automatic validation, and serialize/deserialize data classes to/from many modern file formats.
6+
Various modern file formats (e.g., YAML, JSON, TOML, XML, etc.) are supported, which makes the implementation of the schema-following files in any modern programming language easy (e.g., Python, Julia, C++, LUA, Javascript, etc.).
77
Here, we do Python.
88

99

1010
## Status
1111

12-
This project is a work-in-progress and evolves alongside the Particle Accelerator Lattice Standard (PALS) documents.
12+
This project is a work-in-progress and evolves alongside the Particle Accelerator Lattice Standard ([PALS](https://github.com/campa-consortium/pals)).
1313

1414

1515
## Approach
1616

17-
This project implements the PALS schema in a file agnostic way, mirrored in data objects.
18-
The corresponding serialized files (and optionally, also the corresponding Python objects) can be human-written, human-read, and automatically be validated.
17+
This project implements the PALS schema in a file-agnostic way, mirrored in data objects.
18+
The corresponding serialized files (and optionally, also the corresponding Python objects) can be human-written, human-read, and automatically validated.
1919

2020
PALS files follow a schema and readers can error out on issues.
2121
Not every PALS implementation needs to be as detailed as this reference implementation in Python.
22-
Nonetheless, you can use this implementation to convert between differnt file formats (see above) or to validate a file before reading it with your favorite YAML/JSON/TOML/XML/... library in your programming language of choice.
23-
24-
So let's go, let us use the element descriptions we love and do not spend time anymore on parsing differences between code conventions.
22+
Nonetheless, you can use this implementation to convert between differnt file formats or to validate a file before reading it with your favorite YAML/JSON/TOML/XML/... library in your programming language of choice.
2523

2624
This will enable us to:
27-
- exchange lattices between codes
28-
- use common GUIs for defining lattices
29-
- use common lattice visualization tools (2D, 3D, etc.)
25+
- exchange lattices between codes;
26+
- use common GUIs for defining lattices;
27+
- use common lattice visualization tools (2D, 3D, etc.).
3028

3129

3230
### FAQ
3331

34-
*Why do you use Pydantic for this implementation?*
32+
*Why use Pydantic for this implementation?*
3533
Implementing directly against a specific file format is possible, but cumbersome.
36-
By using widely-used schema engine, we can get the "last" part, serialization and deserialization to various file formats (and converting between them, and validating them) for free.
34+
By using a widely-used schema engine, such as [Pydantic](https://docs.pydantic.dev), we can get serialization/deserialization to/from various file formats, conversion, and validation "for free".
3735

3836

3937
## Roadmap
4038

4139
Preliminary roadmap:
4240

43-
1. Define the PALS schema, using Pydantic
44-
2. Document the API well.
45-
3. Reference implementation in Python
46-
3.1. attract additional reference implementations in other languages.
41+
1. Define the PALS schema, using Pydantic.
42+
2. Document the API.
43+
3. Reference implementation in Python.
44+
3.1. Attract additional reference implementations in other languages.
4745
4. Add supporting helpers, which can import existing MAD-X, Elegant, SXF files.
48-
4.1. Try to be pretty feature complete in these importers (yeah, hard).
49-
5. Implement readers in active community codes for beamline modeling.
50-
Reuse the reference implementations: e.g., we will use this project for the [BLAST codes](https://blast.lbl.gov).
51-
52-
53-
## Examples
54-
55-
### YAML
56-
57-
```yaml
58-
line:
59-
- ds: 1.0
60-
element: drift
61-
nslice: 1
62-
- ds: 0.5
63-
element: sbend
64-
nslice: 1
65-
rc: 5.0
66-
- ds: 0.0
67-
element: marker
68-
name: midpoint
69-
- line:
70-
- ds: 1.0
71-
element: drift
72-
nslice: 1
73-
- ds: 0.0
74-
element: marker
75-
name: otherpoint
76-
- ds: 0.5
77-
element: sbend
78-
name: special-bend
79-
nslice: 1
80-
rc: 5.0
81-
- ds: 0.5
82-
element: sbend
83-
nslice: 1
84-
rc: 5.0
85-
```
86-
87-
### JSON
88-
89-
```json
90-
{
91-
"line": [
92-
{
93-
"ds": 1.0,
94-
"element": "drift",
95-
"nslice": 1
96-
},
97-
{
98-
"ds": 0.5,
99-
"element": "sbend",
100-
"nslice": 1,
101-
"rc": 5.0
102-
},
103-
{
104-
"ds": 0.0,
105-
"element": "marker",
106-
"name": "midpoint"
107-
},
108-
{
109-
"line": [
110-
{
111-
"ds": 1.0,
112-
"element": "drift",
113-
"nslice": 1
114-
},
115-
{
116-
"ds": 0.0,
117-
"element": "marker",
118-
"name": "otherpoint"
119-
},
120-
{
121-
"ds": 0.5,
122-
"element": "sbend",
123-
"name": "special-bend",
124-
"nslice": 1,
125-
"rc": 5.0
126-
},
127-
{
128-
"ds": 0.5,
129-
"element": "sbend",
130-
"nslice": 1,
131-
"rc": 5.0
132-
}
133-
]
134-
}
135-
]
136-
}
137-
```
138-
139-
### Python Dictionary
140-
141-
```py
142-
{
143-
"line": [
144-
{
145-
"ds": 1.0,
146-
"element": "drift",
147-
"nslice": 1
148-
},
149-
{
150-
"ds": 0.5,
151-
"element": "sbend",
152-
"nslice": 1,
153-
"rc": 5.0
154-
},
155-
{
156-
"ds": 0.0,
157-
"element": "marker",
158-
"name": "midpoint"
159-
},
160-
{
161-
"line": [
162-
{
163-
"ds": 1.0,
164-
"element": "drift",
165-
"nslice": 1
166-
},
167-
{
168-
"ds": 0.0,
169-
"element": "marker",
170-
"name": "otherpoint"
171-
},
172-
{
173-
"ds": 0.5,
174-
"element": "sbend",
175-
"name": "special-bend",
176-
"nslice": 1,
177-
"rc": 5.0
178-
},
179-
{
180-
"ds": 0.5,
181-
"element": "sbend",
182-
"nslice": 1,
183-
"rc": 5.0
184-
}
185-
]
186-
}
187-
]
188-
}
189-
```
190-
191-
### Python Dataclass Objects
192-
193-
```py
194-
line=[
195-
Drift(name=None, ds=1.0, nslice=1, element='drift'),
196-
SBend(name=None, ds=0.5, nslice=1, element='sbend', rc=5.0),
197-
Marker(name='midpoint', ds=0.0, element='marker'),
198-
Line(line=[
199-
Drift(name=None, ds=1.0, nslice=1, element='drift'),
200-
Marker(name='otherpoint', ds=0.0, element='marker'),
201-
SBend(name='special-bend', ds=0.5, nslice=1, element='sbend', rc=5.0),
202-
SBend(name=None, ds=0.5, nslice=1, element='sbend', rc=5.0)
203-
])
204-
]
205-
```
46+
4.1. Try to be as feature complete as possible in these importers.
47+
5. Reuse the reference implementations and implement readers in community codes for beamline modeling (e.g., the [BLAST codes](https://blast.lbl.gov)).

0 commit comments

Comments
 (0)