Fields

FieldMesh

FieldMesh(h5=None, data=None)

Class for openPMD External Field Mesh data.

Initialized on on openPMD beamphysics particle group:

• h5: open h5 handle, or str that is a file
• data: raw data

The required data is stored in ._data, and consists of dicts:

• 'attrs'
• 'components'

Component data is always 3D.

Initialization from openPMD-beamphysics HDF5 file:

• FieldMesh('file.h5')

Initialization from a data dict:

• FieldMesh(data=data)

Derived properties:

• .r, .theta, .z
• .Br, .Btheta, .Bz
• .Er, .Etheta, .Ez

• .E, .B

• .phase

• .scale

• .factor

• .harmonic

• .frequency

• .shape

• .geometry
• .mins, .maxs, .deltas
• .meshgrid
• .dr, .dtheta, .dz

Booleans:

• .is_pure_electric
• .is_pure_magnetic
• .is_static

Units and labels

• .units
• .axis_labels

Plotting:

• .plot
• .plot_onaxis

Writers

• .write
• .write_astra_1d
• .write_astra_3d
• .write_gpt
• .write_impact_emfield_cartesian
• .to_cylindrical
• .to_astra_1d
• .to_impact_solrf
• .to_impact_impact_emfield_cartesian
• .write_gpt
• .write_superfish

Constructors (class methods):

• .from_ansys_ascii_3d
• .from_astra_3d
• .from_superfish
• .from_onaxis
• .expand_onaxis

Returned by:

• API Fields  FieldMesh
  •  from_ansys_ascii_3d
  •  from_onaxis

Methods:

• __eq__ –

  Checks that all attributes and component internal data are the same

• __getitem__ –

  Returns component data from a key

• axis_index –

  Returns axis index for a named axis label key.

• axis_points –

  Returns 3D points for the specified axis to be used by the interpolator.

• axis_values –

  Returns the values of the specified field along the given axis, allowing for partial replacement of points.

• component_is_zero –

  Returns True if all elements in a component are zero.

• coord_vec –

  Gets the coordinate vector from a named axis key.

• copy –

  Returns a deep copy

• from_ansys_ascii_3d –

  Class method to return a FieldMesh from ANSYS ASCII files.

• from_astra_3d –

  Class method to parse multiple 3D astra fieldmap files,

• from_impact_emfield_cartesian –

  Class method to read an Impact-T style 1Tv3.T7 file corresponding to

• from_onaxis –

  Parameters

• from_superfish –

  Class method to parse a superfish T7 style file.

• interpolate –

  Interpolates the field data for the given key at specified points.

• interpolator –

  Returns an interpolator for a given field key.

• plot –

  Plots the specified component of the data, with various customization options for appearance and behavior.

• scaled_component –

  Retruns a component scaled by the complex factor

• to_cylindrical –

  Returns a new FieldMesh in cylindrical geometry.

• units –

  Returns the units of any key

• write –

  Writes openPMD-beamphysics format to an open h5 handle, or new file if h5 is a str.

• write_gpt –

  Writes a GPT field file.

• write_impact_emfield_cartesian –

  Writes Impact-T style 1Tv3.T7 file corresponding to

• write_superfish –

  Write a Superfish T7 file.

Attributes:

• axis_labels –
• coord_vecs –

  Uses gridSpacing, gridSize, and gridOriginOffset to return coordinate vectors.

• factor –

  factor to multiply fields by, possibly complex.

• is_pure_electric –

  Returns True if there are no non-zero mageneticField components

• is_pure_magnetic –

  Returns True if there are no non-zero electricField components

• meshgrid –

  Usses coordinate vectors to produce a standard numpy meshgrids.

• phase –

  Returns the complex argument phi = -2*pi*RFphase

Source code in beamphysics/fields/fieldmesh.py

def __init__(self, h5=None, data=None):
    if h5:
        # Allow filename
        if isinstance(h5, str):
            fname = os.path.expandvars(os.path.expanduser(h5))
            assert os.path.exists(fname), f"File does not exist: {fname}"

            with File(fname, "r") as hh5:
                fp = field_paths(hh5)
                assert len(fp) == 1, f"Number of field paths in {h5}: {len(fp)}"
                data = load_field_data_h5(hh5[fp[0]])

        else:
            data = load_field_data_h5(h5)
    else:
        data = load_field_data_dict(data)

    # Internal data
    self._data = data

axis_labels property

axis_labels

coord_vecs property

coord_vecs

Uses gridSpacing, gridSize, and gridOriginOffset to return coordinate vectors.

factor property

factor

factor to multiply fields by, possibly complex.

factor = scale * exp(i*phase)

is_pure_electric property

is_pure_electric

Returns True if there are no non-zero mageneticField components

is_pure_magnetic property

is_pure_magnetic

Returns True if there are no non-zero electricField components

meshgrid property

meshgrid

Usses coordinate vectors to produce a standard numpy meshgrids.

phase property writable

phase

Returns the complex argument phi = -2*pi*RFphase to multiply the oscillating field by.

Can be set.

__eq__

__eq__(other)

Checks that all attributes and component internal data are the same

Source code in beamphysics/fields/fieldmesh.py

def __eq__(self, other):
    """
    Checks that all attributes and component internal data are the same
    """
    if not tools.data_are_equal(self.attrs, other.attrs):
        return False

    return tools.data_are_equal(self.components, other.components)

__getitem__

__getitem__(key)

Returns component data from a key

If the key starts with:

• re_
• im_
• abs_

the appropriate numpy operator is applied.

Source code in beamphysics/fields/fieldmesh.py

def __getitem__(self, key):
    """
    Returns component data from a key

    If the key starts with:

    - `re_`
    - `im_`
    - `abs_`

    the appropriate numpy operator is applied.



    """

    #
    if key in ["r", "theta", "z"]:
        return self.coord_vec(key)

    # Raw components
    if key in self.components:
        return self.components[key]

    # Check for operators
    operator, key = get_operator(key)

    # Scaled components
    if key == "E":
        dat = self.E
    elif key == "B":
        dat = self.B
    else:
        dat = self.scaled_component(key)

    if operator:
        dat = operator(dat)

    return dat

axis_index

axis_index(key)

Returns axis index for a named axis label key.

Examples:

• .axis_labels == ('x', 'y', 'z')
• .axis_index('z') returns 2

Source code in beamphysics/fields/fieldmesh.py

def axis_index(self, key):
    """
    Returns axis index for a named axis label key.

    Examples:

    - `.axis_labels == ('x', 'y', 'z')`
    - `.axis_index('z')` returns `2`
    """
    for i, name in enumerate(self.axis_labels):
        if name == key:
            return i
    raise ValueError(f"Axis not found: {key}")

axis_points

axis_points(axis_label)

Returns 3D points for the specified axis to be used by the interpolator.

Parameters:

• axis_label (str) –

  The label of the coordinate axis. Example: 'r' for cylindrical geometries.

Returns:

• numpy.ndarray of shape (n, 3) –

  An array of 3D points, where the specified axis is populated, and other axes are zero.

Source code in beamphysics/fields/fieldmesh.py

def axis_points(self, axis_label):
    """
    Returns 3D points for the specified axis to be used by the interpolator.

    Parameters
    ----------
    axis_label : str
        The label of the coordinate axis. Example: 'r' for cylindrical geometries.

    Returns
    -------
    numpy.ndarray of shape (n, 3)
        An array of 3D points, where the specified axis is populated, and other axes are zero.
    """
    x = self.coord_vec(axis_label)
    points = np.zeros((len(x), 3))
    points[:, self.axis_index(axis_label)] = x
    return points

axis_values

axis_values(axis_label, field_key, **kwargs)

Returns the values of the specified field along the given axis, allowing for partial replacement of points.

Parameters:

• axis_label (str) –

  The label of the coordinate axis.

• field_key (str) –

  The key representing the field data to interpolate.

• **kwargs (dict, default: {} ) –

  Key-value pairs to replace parts of the internal points array. The keys should be axis labels, and the values should be the corresponding values to set. Example: x=0, y=1 will set points along 'x' and 'y' axes.

Returns:

• tuple(ndarray, ndarray) –

  A tuple containing: - An array of coordinate values along the specified axis. - An array of interpolated field values at the corresponding points.

Source code in beamphysics/fields/fieldmesh.py

def axis_values(self, axis_label, field_key, **kwargs):
    """
    Returns the values of the specified field along the given axis, allowing for partial replacement of points.

    Parameters
    ----------
    axis_label : str
        The label of the coordinate axis.
    field_key : str
        The key representing the field data to interpolate.
    **kwargs : dict
        Key-value pairs to replace parts of the internal points array.
        The keys should be axis labels, and the values should be the corresponding values to set.
        Example: `x=0, y=1` will set points along 'x' and 'y' axes.

    Returns
    -------
    tuple (numpy.ndarray, numpy.ndarray)
        A tuple containing:
        - An array of coordinate values along the specified axis.
        - An array of interpolated field values at the corresponding points.
    """
    points3d = self.axis_points(axis_label)

    # Replace parts of points3d with the values from kwargs
    for axis, value in kwargs.items():
        points3d[:, self.axis_index(axis)] = value

    vec = points3d[:, self.axis_index(axis_label)]
    values = self.interpolate(field_key, points3d)
    return vec, values

component_is_zero

component_is_zero(key)

Returns True if all elements in a component are zero.

Source code in beamphysics/fields/fieldmesh.py

def component_is_zero(self, key):
    """
    Returns True if all elements in a component are zero.
    """
    a = self[key]
    return not np.any(a)

coord_vec

coord_vec(key)

Gets the coordinate vector from a named axis key.

Source code in beamphysics/fields/fieldmesh.py

def coord_vec(self, key):
    """
    Gets the coordinate vector from a named axis key.
    """
    i = self.axis_index(key)
    return np.linspace(self.mins[i], self.maxs[i], self.shape[i])

copy

copy()

Returns a deep copy

Source code in beamphysics/fields/fieldmesh.py

def copy(self):
    """Returns a deep copy"""
    return deepcopy(self)

from_ansys_ascii_3d classmethod

from_ansys_ascii_3d(*, efile=None, hfile=None, frequency=None)

Class method to return a FieldMesh from ANSYS ASCII files.

The format of each file is: header1 (ignored) header2 (ignored) x y z re_fx im_fx re_fy im_fy re_fz im_fz ... in C order, with oscillations as exp(iomegat)

Parameters:

• efile –

  Filename with complex electric field data in V/m

• hfile –

  Filename with complex magnetic H field data in A/m

• frequency –

  Frequency in Hz

Returns:

• FieldMesh –

Source code in beamphysics/fields/fieldmesh.py

@classmethod
def from_ansys_ascii_3d(cls, *, efile=None, hfile=None, frequency=None):
    """
    Class method to return a FieldMesh from ANSYS ASCII files.

    The format of each file is:
    header1 (ignored)
    header2 (ignored)
    x y z re_fx im_fx re_fy im_fy re_fz im_fz
    ...
    in C order, with oscillations as exp(i*omega*t)

    Parameters
    ----------
    efile: str
        Filename with complex electric field data in V/m

    hfile: str
        Filename with complex magnetic H field data in A/m

    frequency: float
        Frequency in Hz

    Returns
    -------
    FieldMesh

    """

    if frequency is None:
        raise ValueError("Please provide a frequency")

    data = read_ansys_ascii_3d_fields(efile, hfile, frequency=frequency)
    return cls(data=data)

from_astra_3d classmethod

from_astra_3d(common_filename, frequency=0)

Class method to parse multiple 3D astra fieldmap files, based on the common filename.

Source code in beamphysics/fields/fieldmesh.py

@classmethod
def from_astra_3d(cls, common_filename, frequency=0):
    """
    Class method to parse multiple 3D astra fieldmap files,
    based on the common filename.
    """

    data = read_astra_3d_fieldmaps(common_filename, frequency=frequency)
    return cls(data=data)

from_impact_emfield_cartesian classmethod

from_impact_emfield_cartesian(filename, frequency=0, eleAnchorPt='beginning')

Class method to read an Impact-T style 1Tv3.T7 file corresponding to the 111: EMfldCart element.

Parameters:

• filename (str) –

  Path to the file where the field data will be written.

• frequency (float, default: 0 ) –

  Fundamental frequency in Hz This simply adds 'fundamentalFrequency' to attrs default=0

Returns:

• FieldMesh –

Source code in beamphysics/fields/fieldmesh.py

@classmethod
def from_impact_emfield_cartesian(
    cls, filename, frequency=0, eleAnchorPt="beginning"
):
    """
    Class method to read an Impact-T style 1Tv3.T7 file corresponding to
    the `111: EMfldCart` element.

    Parameters
    ----------
    filename : str
        Path to the file where the field data will be written.


    frequency : float, optional
        Fundamental frequency in Hz
        This simply adds 'fundamentalFrequency' to attrs
        default=0

    Returns
    -------
        FieldMesh
    """

    attrs, components = parse_impact_emfield_cartesian(filename)

    # These aren't in the file, they must be added
    attrs["fundamentalFrequency"] = frequency
    if frequency == 0:
        attrs["harmonic"] = 0

    attrs["eleAnchorPt"] = eleAnchorPt
    return cls(data=dict(attrs=attrs, components=components))

from_onaxis classmethod

from_onaxis(*, z=None, Bz=None, Ez=None, frequency=0, harmonic=None, eleAnchorPt='beginning')

Parameters:

• z –

  z-coordinates. Must be regularly spaced.

• Bz –

  magnetic field at r=0 in T Default: None

• Ez –

  Electric field at r=0 in V/m Default: None

• frequency –

  fundamental frequency in Hz. Default: 0

• harmonic –

  Harmonic of the fundamental the field actually oscillates at. Default: 1 if frequency !=0, otherwise 0.

• eleAnchorPt –

  Element anchor point. Should be one of 'beginning', 'center', 'end' Default: 'beginning'

Returns:

• field ( FieldMesh ) –

  Instantiated fieldmesh

Source code in beamphysics/fields/fieldmesh.py

@classmethod
def from_onaxis(
    cls,
    *,
    z=None,
    Bz=None,
    Ez=None,
    frequency=0,
    harmonic=None,
    eleAnchorPt="beginning",
):
    """


    Parameters
    ----------
    z: array
        z-coordinates. Must be regularly spaced.

    Bz: array, optional
        magnetic field at r=0 in T
        Default: None

    Ez: array, optional
        Electric field at r=0 in V/m
        Default: None

    frequency: float, optional
        fundamental frequency in Hz.
        Default: 0

    harmonic: int, optional
        Harmonic of the fundamental the field actually oscillates at.
        Default: 1 if frequency !=0, otherwise 0.

    eleAnchorPt: str, optional
        Element anchor point.
        Should be one of 'beginning', 'center', 'end'
        Default: 'beginning'


    Returns
    -------
    field: FieldMesh
        Instantiated fieldmesh

    """

    # Get spacing
    nz = len(z)
    dz = np.diff(z)
    if not np.allclose(dz, dz[0]):
        raise NotImplementedError("Irregular spacing not implemented")
    dz = dz[0]

    components = {}
    if Ez is not None:
        Ez = np.squeeze(np.array(Ez))
        if Ez.ndim != 1:
            raise ValueError(f"Ez ndim = {Ez.ndim} must be 1")
        components["electricField/z"] = Ez.reshape(1, 1, len(Ez))

    if Bz is not None:
        Bz = np.squeeze(np.array(Bz))
        if Bz.ndim != 1:
            raise ValueError(f"Bz ndim = {Bz.ndim} must be 1")
        components["magneticField/z"] = Bz.reshape(1, 1, len(Bz))

    if Bz is None and Ez is None:
        raise ValueError("Please enter Ez or Bz")

    # Handle harmonic options
    if frequency == 0:
        harmonic = 0
    elif harmonic is None:
        harmonic = 1

    attrs = {
        "eleAnchorPt": eleAnchorPt,
        "gridGeometry": "cylindrical",
        "axisLabels": np.array(["r", "theta", "z"], dtype="<U5"),
        "gridLowerBound": np.array([0, 0, 0]),
        "gridOriginOffset": np.array([0.0, 0.0, z.min()]),
        "gridSpacing": np.array([0.0, 0.0, dz]),
        "gridSize": np.array([1, 1, nz]),
        "harmonic": harmonic,
        "fundamentalFrequency": frequency,
        "RFphase": 0,
        "fieldScale": 1.0,
    }

    data = dict(attrs=attrs, components=components)
    return cls(data=data)

from_superfish classmethod

from_superfish(filename, type=None, geometry='cylindrical')

Class method to parse a superfish T7 style file.

Source code in beamphysics/fields/fieldmesh.py

@classmethod
def from_superfish(cls, filename, type=None, geometry="cylindrical"):
    """
    Class method to parse a superfish T7 style file.
    """
    data = read_superfish_t7(filename, type=type, geometry=geometry)
    c = cls(data=data)
    return c

interpolate

interpolate(key, points)

Interpolates the field data for the given key at specified points.

Parameters:

• key (str) –

  The key representing the field data to interpolate.

• points (numpy.ndarray of shape (3,) or (n, 3)) –

  An array of n 3d points at which to interpolate the field data. The points should be ordered according to .axis_labels.

Returns:

• ndarray –

  The interpolated field values at the specified points.

Source code in beamphysics/fields/fieldmesh.py

def interpolate(self, key, points):
    """
    Interpolates the field data for the given key at specified points.

    Parameters
    ----------
    key : str
        The key representing the field data to interpolate.
    points : numpy.ndarray of shape (3,) or (n, 3)
        An array of n 3d points at which to interpolate the field data. The points should
        be ordered according to `.axis_labels`.

    Returns
    -------
    numpy.ndarray
        The interpolated field values at the specified points.
    """
    points = np.array(points)

    # Convenience for a single point
    if len(points.shape) == 1:
        return self.interpolator(key)([points])[0]

    return self.interpolator(key)(points)

interpolator

interpolator(key)

Returns an interpolator for a given field key.

Parameters:

• key (str) –

  The key representing the field data to interpolate. Examples include: - 'Ez' for scaled/phased data - 'magneticField/y' for raw component data

Returns:

• RegularGridInterpolator –

  An interpolator object that can be used to interpolate points. The points to interpolate should be ordered according to .axis_labels.

Source code in beamphysics/fields/fieldmesh.py

def interpolator(self, key):
    """
    Returns an interpolator for a given field key.

    Parameters
    ----------
    key : str
        The key representing the field data to interpolate. Examples include:
        - 'Ez' for scaled/phased data
        - 'magneticField/y' for raw component data

    Returns
    -------
    RegularGridInterpolator
        An interpolator object that can be used to interpolate points. The points
        to interpolate should be ordered according to `.axis_labels`.
    """
    field = self[key]
    return RegularGridInterpolator(
        tuple(map(self.coord_vec, self.axis_labels)), field
    )

plot

plot(component=None, *, cmap=None, nice=True, stream=False, mirror=None, density=2, linewidth=1, arrowsize=1, axes=None, return_figure=False, **kwargs)

Plots the specified component of the data, with various customization options for appearance and behavior.

Parameters:

• component (str, default: None ) –

  The component of the data to be plotted (e.g., 'Ex', 'B'). If None, defaults to 'B' for pure magetic fields, otherwise 'E'

• cmap (str or Colormap, default: None ) –

  The colormap to use for the plot. Defaults to a default colormap if not provided.

• stream (bool, default: False ) –

  If True, adds streamlines to the plot (useful for vector field visualization). Defaults to False.

• mirror (str, default: None ) –

  'r' symmetrizes the data in the r plane. Only for cylindrical plots with r = 0 on the edge of the data Defaults to None.

• density (float, default: 2 ) –

  The density of streamlines when stream=True. Higher values result in more streamlines. Defaults to 1.

• linewidth (float, default: 1 ) –

  The line width for streamlines. Defaults to 1.

• arrowsize (float, default: 1 ) –

  The size of arrows for streamlines when stream=True. Defaults to 1.

• axes (Axes, default: None ) –

  A matplotlib Axes object on which to draw the plot. If None, a new figure and axes will be created.

• return_figure (bool, default: False ) –

  If True, returns the matplotlib Figure object. Defaults to False.

• **kwargs (dict, default: {} ) –

  Additional keyword arguments passed to the underlying plotting functions.

Returns:

• Figure or None –

  Returns the matplotlib Figure object if return_figure=True. Otherwise, the function does not return a value.

Notes

• If axes is provided, the plot will be drawn on the given axes.
• Symmetrizing the data is useful for visualizing symmetric datasets, but it modifies the data displayed.
• The stream parameter is intended for vector field visualization and works best with continuous data.

Examples:

Plot a single component with a specific colormap:

>>> obj.plot(component='x', cmap='viridis')

Plot with streamlines and return the figure:

>>> fig = obj.plot(stream=True, return_figure=True)

Symmetrize the data before plotting:

>>> obj.plot(symmetrize=True)

Customize the appearance of streamlines:

>>> obj.plot(stream=True, density=2, linewidth=0.5, arrowsize=2)

Source code in beamphysics/fields/fieldmesh.py

def plot(
    self,
    component=None,
    *,
    # time=None,
    cmap=None,
    nice=True,
    stream=False,
    mirror=None,
    density=2,
    linewidth=1,
    arrowsize=1,
    axes=None,
    return_figure=False,
    **kwargs,
):
    """
    Plots the specified component of the data, with various customization options for appearance and behavior.

    Parameters
    ----------
    component : str, optional
        The component of the data to be plotted (e.g., 'Ex', 'B'). If None, defaults to
        'B' for pure magetic fields, otherwise 'E'
    cmap : str or matplotlib.colors.Colormap, optional
        The colormap to use for the plot. Defaults to a default colormap if not provided.
    stream : bool, optional
        If True, adds streamlines to the plot (useful for vector field visualization). Defaults to False.
    mirror : str, optional
        'r' symmetrizes the data in the r plane.
        Only for cylindrical plots with r = 0 on the edge of the data
        Defaults to None.
    density : float, optional
        The density of streamlines when `stream=True`. Higher values result in more streamlines. Defaults to 1.
    linewidth : float, optional
        The line width for streamlines. Defaults to 1.
    arrowsize : float, optional
        The size of arrows for streamlines when `stream=True`. Defaults to 1.
    axes : matplotlib.axes.Axes, optional
        A matplotlib Axes object on which to draw the plot. If None, a new figure and axes will be created.
    return_figure : bool, optional
        If True, returns the matplotlib Figure object. Defaults to False.
    **kwargs : dict
        Additional keyword arguments passed to the underlying plotting functions.

    Returns
    -------
    matplotlib.figure.Figure or None
        Returns the matplotlib Figure object if `return_figure=True`. Otherwise, the function does not return a value.

    Notes
    -----
    - If `axes` is provided, the plot will be drawn on the given axes.
    - Symmetrizing the data is useful for visualizing symmetric datasets, but it modifies the data displayed.
    - The `stream` parameter is intended for vector field visualization and works best with continuous data.

    Examples
    --------
    Plot a single component with a specific colormap:
    >>> obj.plot(component='x', cmap='viridis')

    Plot with streamlines and return the figure:
    >>> fig = obj.plot(stream=True, return_figure=True)

    Symmetrize the data before plotting:
    >>> obj.plot(symmetrize=True)

    Customize the appearance of streamlines:
    >>> obj.plot(stream=True, density=2, linewidth=0.5, arrowsize=2)
    """

    time = None  # not yet implemented

    if self.geometry == "cylindrical":
        return plot_fieldmesh_cylindrical_2d(
            self,
            component=component,
            time=time,
            axes=axes,
            return_figure=return_figure,
            cmap=cmap,
            stream=stream,
            mirror=mirror,
            density=density,
            linewidth=linewidth,
            arrowsize=arrowsize,
            **kwargs,
        )
    elif self.geometry == "rectangular":
        plot_fieldmesh_rectangular_2d(
            self,
            component=component,
            time=time,
            axes=axes,
            return_figure=return_figure,
            nice=nice,
            cmap=cmap,
            **kwargs,
        )

    else:
        raise NotImplementedError(f"Geometry {self.geometry} not implemented")

scaled_component

scaled_component(key)

Retruns a component scaled by the complex factor factor = scaleexp(iphase)

Source code in beamphysics/fields/fieldmesh.py

def scaled_component(self, key):
    """

    Retruns a component scaled by the complex factor
        factor = scale*exp(i*phase)


    """

    if key in self.components:
        dat = self.components[key]
    # Aliases
    elif key in component_from_alias:
        comp = component_from_alias[key]
        if comp in self.components:
            dat = self.components[comp]
        else:
            # Component not present, make zeros
            return np.zeros(self.shape)
    else:
        raise ValueError(f"Component not available: {key}")

    # Multiply by scale factor
    factor = self.factor

    if factor != 1:
        return factor * dat
    else:
        return dat

to_cylindrical

to_cylindrical()

Returns a new FieldMesh in cylindrical geometry.

If the current geometry is rectangular, this will use the y=0 slice.

Source code in beamphysics/fields/fieldmesh.py

def to_cylindrical(self):
    """
    Returns a new FieldMesh in cylindrical geometry.

    If the current geometry is rectangular, this
    will use the y=0 slice.

    """
    if self.geometry == "rectangular":
        return FieldMesh(
            data=fieldmesh_rectangular_to_cylindrically_symmetric_data(self)
        )
    elif self.geometry == "cylindrical":
        return self
    else:
        raise NotImplementedError(f"geometry not implemented: {self.geometry}")

units

units(key)

Returns the units of any key

Source code in beamphysics/fields/fieldmesh.py

def units(self, key):
    """Returns the units of any key"""

    # Strip any operators
    _, key = get_operator(key)

    # Fill out aliases
    if key in component_from_alias:
        key = component_from_alias[key]

    return pg_units(key)

write

write(h5, name=None)

Writes openPMD-beamphysics format to an open h5 handle, or new file if h5 is a str.

Source code in beamphysics/fields/fieldmesh.py

def write(self, h5, name=None):
    """
    Writes openPMD-beamphysics format to an open h5 handle, or new file if h5 is a str.

    """
    if isinstance(h5, str):
        fname = os.path.expandvars(os.path.expanduser(h5))
        h5 = File(fname, "w")
        pmd_field_init(h5, externalFieldPath="/ExternalFieldPath/%T/")
        g = h5.create_group("/ExternalFieldPath/1/")
    else:
        g = h5

    write_pmd_field(g, self.data, name=name)

write_gpt

write_gpt(filePath, asci2gdf_bin=None, verbose=True)

Writes a GPT field file.

Source code in beamphysics/fields/fieldmesh.py

def write_gpt(self, filePath, asci2gdf_bin=None, verbose=True):
    """
    Writes a GPT field file.
    """

    return write_gpt_fieldmap(
        self, filePath, asci2gdf_bin=asci2gdf_bin, verbose=verbose
    )

write_impact_emfield_cartesian

write_impact_emfield_cartesian(filename)

Writes Impact-T style 1Tv3.T7 file corresponding to the 111: EMfldCart element.

The file will contain grid information for X, Y, and Z dimensions followed by field values. The field values are stored as complex numbers in the format (real, imaginary).

Parameters:

• filename (str) –

  Path to the file where the field data will be written.

Source code in beamphysics/fields/fieldmesh.py

def write_impact_emfield_cartesian(self, filename):
    """
    Writes Impact-T style 1Tv3.T7 file corresponding to
    the `111: EMfldCart` element.

    The file will contain grid information for X, Y, and Z dimensions followed by field values.
    The field values are stored as complex numbers in the format (real, imaginary).

    Parameters
    ----------
    filename : str
        Path to the file where the field data will be written.
    """
    return write_impact_emfield_cartesian(self, filename)

write_superfish

write_superfish(filePath, verbose=False)

Write a Superfish T7 file.

For static fields, a Poisson T7 file is written.

For dynamic (harmonic /= 0) fields, a Fish T7 file is written

If .is_static, a Poisson file is written. Otherwise a Fish file is written.

Parameters:

• filePath (str or Path) –

  Output file path.

Source code in beamphysics/fields/fieldmesh.py

def write_superfish(self, filePath, verbose=False):
    """
    Write a Superfish T7 file.

    For static fields, a Poisson T7 file is written.

    For dynamic (`harmonic /= 0`) fields, a Fish T7 file is written

    If .is_static, a Poisson file is written. Otherwise a Fish file is written.

    Parameters
    ----------
    filePath : str or pathlib.Path
        Output file path.
    """
    return write_superfish_t7(self, filePath, verbose=verbose)