Genesis 4 Lattice¶
genesis.version4.Lattice ¶
Lattice(elements=None, *, filename=None)
Bases: BaseModel
A Genesis 4 beamline Lattice configuration.
Attributes:
Name | Type | Description |
---|---|---|
elements |
list of BeamlineElement or Line
|
Elements contained in the lattice. |
filename |
Path or None
|
The filename from which this lattice was loaded. |
Source code in genesis/version4/input/lattice.py
346 347 348 349 350 351 352 353 354 355 356 357 358 |
|
Attributes¶
genesis.version4.Lattice.by_element
property
¶
by_element
Get beamline elements organized by their class.
genesis.version4.Lattice.phase_shifters
property
¶
phase_shifters
List of all PhaseShifter instances.
Functions¶
genesis.version4.Lattice.by_z_location ¶
by_z_location(beamline, limit_to=None)
Get all (flattened) beamline elements by Z location.
Returns:
Type | Description |
---|---|
list of (zend, element)
|
Each list item is a ZElement, a namedtuple which has |
Source code in genesis/version4/input/lattice.py
782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 |
|
genesis.version4.Lattice.fix_labels ¶
fix_labels()
Fix labels of elements based on their dictionary key in .elements
.
Source code in genesis/version4/input/lattice.py
860 861 862 863 864 865 866 867 868 869 870 |
|
genesis.version4.Lattice.flatten_line ¶
flatten_line(beamline, *, count=1, start=0, format='L{index}_{name}', in_place=True, new_beamline='')
Flatten a beamline such that any nested beamlines are made into distinct elements.
For example, take a beamline LN
which contains 2 nested beamlines
"L1" (containing UND) and "L2" (containing QUAD).
Flattening this with the default format of L{index}_{name}
would result with replacing LN
with:
* L0_UND
and L0_QUAD
(wtih start=0, count=1)
* L1_UND
, L1_QUAD
, L2_UND
, L2_QUAD
(with start=1, count=2)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
beamline |
str
|
The beamline name to flatten. |
required |
count |
int
|
The number of times to duplicate the flattened beamline. |
1
|
start |
int
|
The starting index for relabeling elements. |
0
|
format |
str
|
The string format to use for renaming beamline elements. |
"L{index}_{name}"
|
in_place |
bool
|
Perform the flattening in-place. Remove unused elements and add the new elements directly to the lattice. |
True
|
new_beamline |
str
|
For in-place mode, use this as the name for the new beamline. |
''
|
Returns:
Type | Description |
---|---|
[segment(start), segment(start+1), ... segment(start+count-1)]
|
Each segment corresponds to a single index of the flattened line,
from |
Source code in genesis/version4/input/lattice.py
703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 |
|
genesis.version4.Lattice.from_contents
classmethod
¶
from_contents(contents, filename=None)
Load a lattice from its file contents.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
contents |
str
|
The contents of the lattice file. |
required |
filename |
AnyPath or None
|
The filename of the lattice, if known. |
None
|
Returns:
Type | Description |
---|---|
Lattice
|
|
Source code in genesis/version4/input/lattice.py
927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 |
|
genesis.version4.Lattice.from_elements
classmethod
¶
from_elements(elements, filename=None)
Create a Lattice from a list of labeled elements.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
elements |
list of BeamlineElement
|
Elements of the beamline. These must have a label set. |
required |
filename |
AnyPath or None
|
The filename of the lattice, if applicable. |
None
|
Returns:
Type | Description |
---|---|
Lattice
|
|
Source code in genesis/version4/input/lattice.py
977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 |
|
genesis.version4.Lattice.from_file
classmethod
¶
from_file(filename)
Load a lattice file from disk.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filename |
AnyPath
|
The filename to load. |
required |
Returns:
Type | Description |
---|---|
Lattice
|
|
Source code in genesis/version4/input/lattice.py
959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 |
|
genesis.version4.Lattice.inspect_line ¶
inspect_line(beamline)
Returns a list of all elements in the given beamline.
This recursively inspects any LINEs inside the beamline.
Returns:
Type | Description |
---|---|
list of BeamlineElement
|
List of beamline element instances. |
Source code in genesis/version4/input/lattice.py
686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 |
|
genesis.version4.Lattice.inspect_line_by_name ¶
inspect_line_by_name(beamline)
Returns a list of all element names in the given beamline.
This recursively inspects any LINEs inside the beamline.
Returns:
Type | Description |
---|---|
list of str
|
List of names. |
Source code in genesis/version4/input/lattice.py
668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 |
|
genesis.version4.Lattice.is_flat ¶
is_flat(beamline)
Checks if the given beamline
does not reuse elements.
Source code in genesis/version4/input/lattice.py
625 626 627 628 |
|
genesis.version4.Lattice.model_dump ¶
model_dump(**kwargs)
Serialize this lattice to a list of dictionaries.
Source code in genesis/version4/input/lattice.py
921 922 923 924 925 |
|
genesis.version4.Lattice.plot ¶
plot(beamline=None, *, ax=None, show_labels=True, show=True, normalize_aw=False, figsize=None, xlim=None, ylim=None)
Plot the layout of the given beamline.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
beamline |
str
|
The name of the beamline. |
None
|
ax |
Axes or None
|
Plot on the given axis, or create a new one. |
None
|
show_labels |
bool
|
Show labels for each undulator. |
True
|
show |
bool
|
Show the plot. |
True
|
normalize_aw |
bool
|
Normalize undulator strengths with respect to the first undulator (\(aw0\)): \(aw / aw0 - 1\) |
False
|
figsize |
Tuple[float, float]
|
The figure size to create. Used if |
None
|
xlim |
Tuple[float, float]
|
X axis limits for the plot. |
None
|
ylim |
Tuple[float, float]
|
Y axis limits for the plot. |
None
|
Source code in genesis/version4/input/lattice.py
520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 |
|
genesis.version4.Lattice.taper_array ¶
taper_array(beamline, aws)
Apply a list of undulator strengths to set the taper.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
beamline |
str
|
The beamline name. |
required |
aws |
list of floats (or equivalent, np.ndarray)
|
The undulator strengths, one for each undulator in the beamline. Undulators are sorted based on Z position. |
required |
Source code in genesis/version4/input/lattice.py
418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 |
|
genesis.version4.Lattice.taper_custom ¶
taper_custom(beamline, *, aw0, zstart, zend)
Get a list of undulators to perform a custom taper on.
Only elements that fit within the range [zstart, zend] will be included.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
beamline |
str
|
The beamline containing the undulators. |
required |
aw0 |
float
|
The starting undulator strength. |
required |
zstart |
float
|
The starting Z position, relative to the first element on the line. |
required |
zend |
float
|
The ending Z position, relative to the first element on the line. |
required |
Returns:
Type | Description |
---|---|
list of ZElement
|
List of ZElement instances, which contain a normalized Z location (zstart=0.0, zend=1.0) and an Undulator element. |
Source code in genesis/version4/input/lattice.py
360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 |
|
genesis.version4.Lattice.taper_linear ¶
taper_linear(beamline, *, aw0, zstart, zend, taper_start, taper_end)
Perform a linear taper on undulators in the given beamline.
Only elements that fit within the range [zstart, zend] will be included.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
beamline |
str
|
The beamline containing the undulators. |
required |
aw0 |
float
|
The starting undulator strength. |
required |
zstart |
float
|
The starting Z position, relative to the first element on the line. |
required |
zend |
float
|
The ending Z position, relative to the first element on the line. |
required |
taper_start |
float
|
The starting taper multiplier (applied to |
required |
taper_end |
float
|
The final taper multiplier (applied to |
required |
Returns:
Type | Description |
---|---|
list of float
|
List of undulator strengths. |
Source code in genesis/version4/input/lattice.py
452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 |
|
genesis.version4.Lattice.to_file ¶
to_file(filename)
Write the lattice input file, in Genesis format, to filename
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filename |
str or Path
|
|
required |
Source code in genesis/version4/input/lattice.py
1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 |
|
genesis.version4.Lattice.to_genesis ¶
to_genesis()
Generate a Genesis 4-compatible lattice input string.
Source code in genesis/version4/input/lattice.py
855 856 857 858 |
|
Beamline Elements¶
genesis.version4.Chicane ¶
Bases: BeamlineElement
Lattice beamline element: chicane.
Chicane corresponds to Genesis 4 beamlineelement chicane
.
Attributes:
Name | Type | Description |
---|---|---|
L |
float, default=0.0
|
Length of the chicane, which consists out of 4 dipoles without focusing. The first and last are placed at the beginning and end of the reserved space. The inner ones are defined by the drift length in between. Any remaining distance, namely the length subtracted by 4 times the dipole length and twice the drift length are placed between the second and third dipole. |
lb |
float, default=0.0
|
Length of an individual dipole in meter. |
ld |
float, default=0.0
|
Drift between the outer and inner dipoles, projected onto the undulator axis. The actual path length is longer by the factor \(1/\cos\theta\), where \(\theta\) is the bending angle of an individual dipole. |
delay |
float, default=0.0
|
Path length difference between the straight path and the actual trajectory in
meters. Genesis 1.3 calculates the bending angle internally starting from this
value. \(R_{56} = 2\) |
genesis.version4.Corrector ¶
Bases: BeamlineElement
Lattice beamline element: corrector.
Corrector corresponds to Genesis 4 beamlineelement corrector
.
Attributes:
Name | Type | Description |
---|---|---|
L |
float, default=0.0
|
Length of the corrector in meter. |
cx |
float, default=0.0
|
Kick angle in \(x\) in units of \(\gamma \beta_x\). |
cy |
float, default=0.0
|
Kick angle in \(y\) in units of \(\gamma \beta_y\). |
genesis.version4.Drift ¶
Bases: BeamlineElement
Lattice beamline element: drift.
Drift corresponds to Genesis 4 beamlineelement drift
.
Attributes:
Name | Type | Description |
---|---|---|
L |
float, default=0.0
|
Length of the drift in meter. |
genesis.version4.Line ¶
Bases: BeamlineElement
A Genesis 4 beamline Line.
Attributes:
Name | Type | Description |
---|---|---|
elements |
list of LineItem
|
Elements contained in the line. |
label |
(str, optional)
|
An optional label to attach to the line. |
Attributes¶
genesis.version4.Line.flattened
property
¶
flattened
Flattened elements by name, including Z location if available.
Functions¶
genesis.version4.Line.from_labels
classmethod
¶
from_labels(elements, *element_labels, label='')
Create a Line
from labeled beamline elements.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
elements |
Dict[str, BeamlineElement]
|
The element dictionary. |
required |
*element_labels |
str
|
Labels of elements. May be either a single label per argument or a whitespace-delimited string of labels. |
()
|
label |
str
|
Label name for the line. |
''
|
Returns:
Type | Description |
---|---|
Line
|
|
Source code in genesis/version4/input/lattice.py
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 |
|
genesis.version4.Marker ¶
Bases: BeamlineElement
Lattice beamline element: marker.
Marker corresponds to Genesis 4 beamlineelement marker
.
Attributes:
Name | Type | Description |
---|---|---|
dumpfield |
int, default=0
|
A non-zero value enforces the dump of the field distribution of this zero length element. |
dumpbeam |
int, default=0
|
A non-zero value enforces the dump of the particle distribution. |
sort |
int, default=0
|
A non-zero value enforces the sorting of particles, if one-for-one simulations are enabled. |
stop |
int, default=0
|
A non-zero value stops the execution of the tracking module. Note that the output file still contains the full length with zeros as output for those integration steps which are no further calculated. |
genesis.version4.PhaseShifter ¶
Bases: BeamlineElement
Lattice beamline element: phase shifter.
PhaseShifter corresponds to Genesis 4 beamlineelement phaseshifter
.
Attributes:
Name | Type | Description |
---|---|---|
L |
float, default=0.0
|
Length of the phase shifter in meter. |
phi |
float, default=0.0
|
Change in the ponderomotive phase of the electrons in units of rad. Note that Genesis 1.3 is doing an autophasing, so that the electrons at reference energy are not changing in ponderomotive phase in drifts. |
genesis.version4.Quadrupole ¶
Bases: BeamlineElement
Lattice beamline element: quadrupole.
Quadrupole corresponds to Genesis 4 beamlineelement quadrupole
.
Attributes:
Name | Type | Description |
---|---|---|
L |
float, default=0.0
|
Length of the quadrupole in meter. |
k1 |
float, default=0.0
|
Normalized focusing strength in 1/m^2. |
x_offset |
float, default=0.0
|
Offset in \(x\) in meter. |
y_offset |
float, default=0.0
|
Offset in \(y\) in meter. |
genesis.version4.Undulator ¶
Bases: BeamlineElement
Lattice beamline element: an undulator.
Undulator corresponds to Genesis 4 beamlineelement undulator
.
Attributes:
Name | Type | Description |
---|---|---|
aw |
float, default=0.0
|
The dimensionless rms undulator parameter. For planar undulator this value is smaller by a factor \(1 / \sqrt{2}\) than its K-value, while for helical undulator rms and peak values are identical. |
lambdau |
float, default=0.0
|
Undulator period length in meter. Default is 0 m. |
nwig |
int, default=0
|
Number of periods. |
helical |
bool, default=False
|
Boolean flag whether the undulator is planar or helical. A planar undulator has
helical= |
kx |
float, default=0.0
|
Roll-off parameter of the quadratic term of the undulator field in x. It is normalized with respect to \(k_u^2\). |
ky |
float, default=1.0
|
Roll-off parameter of the quadratic term of the undulator field in y. |
ax |
float, default=0.0
|
Offset of the undulator module in \(x\) in meter. |
ay |
float, default=0.0
|
Offset of the undulator module in \(y\) in meter. |
gradx |
float, default=0.0
|
Relative transverse gradient of undulator field in \(x\) \(\equiv (1/a_w) \partial a_w/\partial x\). |
grady |
float, default=0.0
|
Relative transverse gradient of undulator field in \(y\) \(\equiv (1/a_w) \partial a_w/\partial y\). |