Module simpa.acc
Package simpa.acc.api.create

Class Sequence

java.lang.Object
simpa.acc.api.create.Sequence
public class Sequence extends Object
Class that represents a sequence of machine elements that make up an accelerator or a transfer line.

  • Field Details

  • Constructor Details

    • Sequence

      public Sequence(String name, boolean circular, LocalFramesCalculator.Strategy strategy, org.apache.commons.math3.geometry.euclidean.threed.Vector3D vertical)
      Constructs a closed or open sequence representing a circular machine or a transfer line. We use the following conventions: - Right handed coordinate systems, both locally and globally. - The Y coordinate of the local coordinate system points up, when the machine is in the X,Z global plane. - The Z coordinate of the local coordinate system points always in the direction of the beam propagation. - A circular machine consisting of bending magnets with positive bending angles will be constructed such, that the Z local coordinate points clockwise. - For positive bending angle the X axis points outside of the circle and inside for negative ones.
      Parameters:
      name - The name of the sequence
      circular - If true, a circular machine will be constructed by connecting the last orbit point to the first one. Setting it false results a transfer line.
      strategy - A strategy to construction the local coordinates see LocalFramesCalculator.Strategy
      vertical - The preferred vertical direction at construction the local coordinates see LocalFramesCalculator

  • Method Details

    • getSequences

      public static HashMap<String,Sequence> getSequences()
      Returns:
      A map of all sequences. The key is the name of the sequence. The value is the sequence itself.

    • getActiveSequence

      public static Sequence getActiveSequence()
      Returns:
      The active sequence.

    • setActiveSequence

      public static void setActiveSequence(Sequence activeSequence)
      Parameters:
      activeSequence - The active sequence.

    • getOptics

      public Optics getOptics()
      Returns:
      The optics belonging to this sequence. It is null until the optics is calculated

    • setOptics

      public void setOptics(Optics optics)
      Sets the optics belonging to this sequence.
      Parameters:
      optics - optics belonging to this sequence.

    • getScalingMap

      public Map<String,Double> getScalingMap()
      Returns:
      A deep copy of the scaling map of this sequence.

    • setScalingMap

      public void setScalingMap(Map<String,Double> scalingMap, boolean enableExternal) throws IOException
      Set the scalings of the elements in the sequence and creates a potential provider from the scaled field maps.
      Parameters:
      scalingMap - A map containing the scaling of the sequence elements. The key is the group name and the value is the scaling factor. A group is usually contains all elements which connected to the same power supply. The value is given usually in Amper for magnetic elements and Volt for electrostatic elements.
      enableExternal - If true, the map can contain field map groups which are not in the sequence. This can be useful when tracking the sequence with some external field disturbance. When true the map will be checked for groups not in the sequence and if found one, an IllegalArgumentException will be thrown.
      Throws:
      IOException

    • updateScalingMap

      public void updateScalingMap(Map<String,Double> newScalings) throws IOException
      Updates the scalings of this sequence with the given scaling map.
      Parameters:
      newScalings - The new scalings. Original scaling not in this map will not be modified. If the new scaling map contains a key not present of the original map, it will be ignored.
      Throws:
      IOException - When a map has not been found.

    • getPotentialProvider

      public PotentialProvider getPotentialProvider()
      Returns:
      returns the potential provider of the sequence.

    • addStraightElementAt

      public void addStraightElementAt(double longiPos, String name, double scaling, String solutionFile, double tilt, String groupName, org.apache.commons.math3.geometry.euclidean.threed.Rotation preRotation, Map<Double,Profile> profileMap)
      Puts a straight element at the end of the beam line at the specified longitudinal position. It is assumed that the Z axis of the local coordinate system of the element to be added points in the direction of the beam propagation.
      Parameters:
      longiPos - Longitudinal position.
      name - A unique name for this specific element. Example:QUAD1
      scaling - A scaling factor for the strength of the sources. Usually this is the same as the current or the voltage in [A] or [V].
      solutionFile - Source arrangement file. called "NAME OF THE ELEMENT TYPE"-SOLUTION.txt Example: QUAD-SOLUTION.txt
      tilt - Tilt angle. This is a rotation along the local Z (S) axis. A positive tilt angle will rotate the element accorging to the right-hand rule for curve orientation.See: https://en.wikipedia.org/wiki/Right-hand_rule
      groupName - Specifies the group at which this element will be added. The elements in the same group will be in the same binary field map after the spherical harmonics expansion. If it is null, the name of the element will be used.
      preRotation - A rotation to be applied before putting the element into the sequence. If the element is oriented according to the conventions, such as the local Z axis coincides with the reference orbit and the local Y axis points up, this should be the identity rotation. Typically used for mis-alignment or put an existing point source with a different orientation.
      profileMap - A Vacuum chamber if any. If null, the default profile will be used at the construction of the beam region.

    • addArbitraryElementAt

      public void addArbitraryElementAt(double longiPos, String name, double scaling, String solutionFile, org.apache.commons.math3.geometry.euclidean.threed.Vector3D localYAxis, String groupName, Map<Double,Profile> profileMap, List<org.apache.commons.math3.geometry.euclidean.threed.Vector3D> path)
      Puts an element with arbitrary shape at the end of the beam line at the specified longitudinal position. Unlike for the bending and straight elements the arbitrary element must accompanied by a path which describes the trajectory of the ideal particle. The element is oriented such that the local Z axis of the element points in the same direction as the last vector in the reference orbit calculated so far. The element is rotated around the Z axis such that the local Y axis of the element points to the direction of the localYAxis parameter. The last vector of the path determines the Z direction at the exit of the element.
      Parameters:
      longiPos - Longitudinal position of the first point of the path.
      name - A unique name for this specific element. Example:QUAD1
      scaling - A scaling factor for the strength of the sources. Usually this is the same as the current or the voltage in [A] or [V].
      solutionFile - Source arrangement file. called "NAME OF THE ELEMENT TYPE"-SOLUTION.txt Example: QUAD-SOLUTION.txt
      localYAxis - The Y direction at the entry of the element.
      groupName - Specifies the group at which this element will be added. The elements in the same group will be in the same binary field map after the spherical harmonics expansion. If it is null, the name of the element will be used.
      profileMap - A Vacuum chamber if any. If null, the default profile will be used at the construction of the beam region.
      path - A list of 3D points describing the reference orbit inside the element.

    • addMarkerElement

      public void addMarkerElement(double longiPos, String name, AccElement.ElementType type, Map<Double,Profile> profileMap)
      Adds a marker element (marker, pickup) to the specified position. If the position is after the last orbit point it extends the orbit.
      Parameters:
      longiPos - Longitudinal position of the marker element.
      name - Name of the marker.
      type - Type of the element.
      profileMap - A Vacuum chamber if any. If null, the default profile will be used at the construction of the beam region.

    • addBendingElementAt

      public void addBendingElementAt(double longiPos, String name, double scaling, String solutionFile, double length, double deflection, double tilt, String groupName, org.apache.commons.math3.geometry.euclidean.threed.Rotation preRotation, Map<Double,Profile> profileMap, boolean sectorBend)
      Puts a bending at the end of the beam line with the center at the given longitudinal position. It is assumed that the Z axis of the local coordinate system at the center of the bending and it points in the direction of the beam propagation.
      Parameters:
      longiPos - Longitudinal position of the bending center.
      name - A unique name for this specific magnet. Example: ELBHZ01
      scaling - A scaling factor for the strength of the sources. Usually this is the same as the current or the voltage in [A] or [V].
      solutionFile - Source strength file, called "NAME OF THE BENDING TYPE"-SOLUTION.txt Example: ELBHZ-SOLUTION.txt
      length - Length of the magnet [meters]
      deflection - Deflection angle [radians]
      tilt - Tilt angle. This is a rotation along the local Z (S) axis. A positive tilt angle will rotate the element accorging to the right-hand rule for curve orientation.See: https://en.wikipedia.org/wiki/Right-hand_rule
      groupName - Specifies the group at which this element will be added. The elements in the same group will be in the same field map after the spherical harmonics expansion. If it is null, the name of the element will be used.
      preRotation - A rotation to be applied before putting the element into the sequence. If the element is oriented according to the conventions this should be the identity rotation. Typically used for misalignment simulation.
      profileMap - A Vacuum chamber if any. If null, the default profile will be used at the construction of the beam region.
      sectorBend - This should be true for a sector bending. If true a half rotation is applied. For a rectangular bend no need for the half rotation, because the orbit in the magnet local frame is aligned with the Z axis, while the sector bending has an angle which is half the deflection angle.

    • addExternalElement

      public void addExternalElement(String name, double scaling, String solutionFile, String groupName, org.apache.commons.math3.geometry.euclidean.threed.Rotation rotation, org.apache.commons.math3.geometry.euclidean.threed.Vector3D translation)
      Adds an accelerator element from a solution file. The the sources from 'elementname-SOLUTION.txt' file is read. Then the sources are scaled, rotated and translated and an AccSourceArrangement will be added to the sequence. The reference orbit is not affected.
      Parameters:
      name - Name of the element.
      scaling - Scaling factor for the sources.
      solutionFile - File named according to the file naming conventions.FileNamingConventions containing the sources.
      groupName - Group name to which this element belongs to.
      rotation - Rotation applied before the translation.
      translation - Translation to be applied after the rotation.

    • getSourceArrangementGroups

      public HashMap<String,List<SourceArrangement>> getSourceArrangementGroups()
      Gets the map of SourceArrangment groups in the sequence. The key is the group name, the value is a list of SourceArrangement instances.
      Returns:
      Map of element groups.

    • getReferenceOrbit

      public ReferenceOrbit getReferenceOrbit()
      Gets the reference orbit of the sequence.
      Returns:
      the reference orbit.

    • getCurrentLength

      public double getCurrentLength()
      This method returns the current length of the sequence. Unlike the orbit length which is available only when the sequence construction is finished, the current length is available during the construction of the sequence.
      Returns:
      The current length of the sequence.

    • getLocalOrigins

      public Map<String,org.apache.commons.math3.geometry.euclidean.threed.Vector3D> getLocalOrigins()
      Gets a list of vectors pointing to the local origins of the elements in the sequence. The coordinates of the vectors are expressed in the global coordinate system.
      Returns:
      List of local origins of the elements

    • getVacuumChambers

      public List<VacuumChamber> getVacuumChambers()
      Gets a list of oriented and positioned vacuum chambers along the reference orbit.
      Returns:
      List of chambers in the sequence.

    • sourcePositionsToFile

      public void sourcePositionsToFile(String fileName)
      Writes a text file containing all source positions to the given file. For each source there is a line in the file.
      Parameters:
      fileName - Name of the output file.

    • getSourceArrangements

      public List<SourceArrangement> getSourceArrangements()
      Gets a list of the SourceArrangement objects in the sequence.
      Returns:
      list of all source arrangements.

    • getFrozen

      public boolean getFrozen()
      Gets a boolean that tells whether the sequence is frozen or not.
      Returns:
      true if the sequence is frozen.

    • setFozen

      public void setFozen(boolean frozen)
      Used for indicating when a sequence is frozen. If the sequence has been frozen, not possible to add elements to it anymore.
      Parameters:
      frozen - Set this true if want to set the sequence is frozen.

    • isCircular

      public boolean isCircular()
      Returns:
      true if it is a ring.

    • getName

      public String getName()
      Returns:
      The name of the sequence.

    • getAccElements

      public Map<String,AccElement> getAccElements()
      Returns:
      A map of AccElements of this sequence, with the name of the element as the key.

    • getOrbitStep

      public double getOrbitStep()
      Returns:
      Step size for the orbit.

    • setOrbitStep

      public void setOrbitStep(double orbitStep)
      Set the step size for the orbit. By default it is 0.01 [m].
      Parameters:
      orbitStep - Step size for the orbit.

    • getScalingMapString

      public String getScalingMapString()
      Returns a scaling map as a string in SIMPA format. The scaling map is is sorted by the longitudinal position of the elements.
      Returns:
      A string representation of the scaling map.