ess.fieldmap

Main description of this module is not written yet

v0.1:

Now that TraceWin can also convert binary fieldmaps to ASCII the main usage is reduced to trimming fieldmaps – M. Eshraqi 2018 July 09

v0.2:

Added function to read ASCII fieldmaps and added descriptions Added function save_to_ascii Added function batch_convert_to_Ascci – M. Eshraqi 2018 July 23

v0.3:

minor bug fixed in 2D fields added function unify_grid_size

v0.4:

added function create_tw_fieldmap added function uniform_mesh fixed a bug in function save_to_ascii which was writing Nx, Ny and Nz as floats – M. Eshraqi 2018 Aug 09

From TraceWin manual:

The field map file syntax is the following in the BINARY format:

  • Dimension 1

    nz (integer 4 bytes) zmax (double 8 bytes)
Norm (double 8 bytes)

# Nz Zmax
# Norm

for k=0 to nz
    Fz(k.zmax/nz) (float 4 bytes)

  • Dimension 2

    nz (integer 4 bytes) zmax (double 8 bytes)
nx (integer 4 bytes) xmax (double 8 bytes)
Norm (double 8 bytes)

# Nz Zmax
# Nx Xmax
# Norm

for k=0 to nz
    for i=0 to nr
        Fz(k*zmax/nz, i*rmax/nr) (float 4 bytes)

  • Dimension 3

    (Be careful about  the dimension order)
nz (integer 4 bytes) zmax (double 8 bytes)
nx (integer 4 bytes) xmin (double 8 bytes) xmax (double 8 bytes)
ny (integer 4 bytes) ymin (double 8 bytes) ymax (double 8 bytes)
Norm (double 8 bytes)
Be careful about  the dimension order

# Nz Zmax
# Nx Xmin Xmax
# Ny Ymin Ymax
# Norm

for k=0 to nz
    for j=0 to ny
        for i=0 to nx
            Fz(k*zmax/nz, ymin+j*(ymax-ymin)/ny, xmin+i*(xmax-xmin)/nx) (float 4 bytes)

Warning: The lattice has to be regular. The normalization factor is equal to ke/Norm or kb/Norm. Fz are in MV/m for electric field or in T for magnetic field. The dimensions are in meter.

ess.fieldmap.batch_convert_to_ascii(binary_field_path: str, fieldmap_dim: int)[source]
Parameters

  • binary_field_path (string) – path to the binary files to be converted to ASCII format

  • fieldmap_dim (int) – dimension of the fieldmap to be converted

ess.fieldmap.batch_cut_fieldmap(fieldmaps_path: str, fieldmap_dim: int, entrance_rows_cut: int, exit_rows_cut: int, file_type: str)[source]

Saves a TraceWin readable ASCII file

Parameters

  • fieldmaps_ path (string) – path to the fieldmap folder (ASCII or binary) excluding the trailing / and filename

  • fieldmap_dim (int) – dimension of the fieldmap, 1, 2 and 3 for 1D, 2D and 3D TraceWin formatted fieldmap

  • entrance_rows_cut (int) – number of data rows to be removed from array from the entrance side of the field

  • exit_rows_cut (int) – number of data rows to be removed from array from the exit side of the field

  • file_type (str) – ‘b’ for binary and ‘a’ for ascii fieldmap files.

ess.fieldmap.convert_3d_to_1d(path: str, map_name: str, map_type: str = 'electric', file_type: str = 'a', dist_from_axis: float = 0.0)[source]
Parameters

  • path (str) – path to the field map

  • map_name (str) – name of field map

  • map_type (str) – electric [default] or magnetic

  • file_type (str) – ‘b’ for binary and ‘a’ for ascii field map files.

  • dist_from_axis (float) – In case of magnetic quadrupole field, the distance from axis where field is read (T/m). Unit m. Ignored if map_type is electric.

Returns

  • Saves 1D field map to file. Currently overwriting automatically (renaming original) so careful.

  • Example

  • fieldmap.convert_3d_to_1d(‘mebt’, ‘MEBT_Q’, ‘magnetic’, ‘a’, 0.003)

ess.fieldmap.create_tw_fieldmap(fieldmaps_path: str, tabular_file_name: str, fieldmap_dim: int = 1, n_col: int = 1, skiprows: int = 0, comments: str = '#', extensions=['F1', 'F2', 'F3', 'F4', 'F5', 'F6'], xyz=[1, 2, 3], delimiter=None)[source]
Parameters

  • fieldmaps_path (str) – path to the fieldmap

  • tabular_file_name (file name) – tabular data with coordinates z, x and y or z and r or only z depending on dimension as first 1-3 cols. n_col is the number of data columns except coordinate ones (1-6) coordinates should be on a uniform grid on each axis (but different axes are independent)

  • fieldmap_dim (int) – dimension of the fieldmap data

  • n_col (int) – number of data columns in fieldmap

  • skiprows (int) – number of header lines to skip

  • comments (str) – Comment lines start with this character

  • extensions (list) – list of column names to be used for naming the files, default is [F1, F2, F3, F4, F5, F6]

  • xyz (list) – order of columns, xyz = [col_number(x), col), col_number(y), col_number(z)] e.g.if column 1 is x, col 2 is y and col 3 is z, xyz list = [1,2,3] (default)

  • delimiter (string) – Delimiter character that separates columns. Default is whitespace

ess.fieldmap.cut_fieldmap_length(filepath: str, fieldmap_dim: int, entrance_rows_cut: int, exit_rows_cut: int, file_type: str)[source]
Parameters

  • filepath (string) – path to the fieldmap file (ASCII or binary) including the path, file name and extension

  • fieldmap_dim (int) – dimension of the fieldmap, 1, 2 and 3 for 1D, 2D and 3D TraceWin formatted fieldmap

  • entrance_rows_cut (int) – number of data rows to be removed from array from the entrance side of the field

  • exit_rows_cut (int) – number of data rows to be removed from array from the exit side of the field

  • file_type (str) – ‘b’ for binary and ‘a’ for ascii fieldmap files.

Returns

  • a list containing Header and Field

  • Header (1D array of size 3, 5, 9 (for 1D, 2D and 3D fieldmaps)) – TraceWin fieldmap header info

  • Field (1D numpy array containing the nD field data with only the remaining rows)

Raises

prints a message if the file_type is not specified to be a (ascii) or b (binary) –

Todo

cutting the field in other directions

ess.fieldmap.field_on_axis(header, field, fieldmap_dim: int, x_on_axis: float = 0, y_on_axis: float = 0)[source]
Parameters

  • header (1D numpy array of size 3, 5, 9 (for 1D, 2D and 3D field maps)) – TraceWin field map header info

  • field (1D numpy array containing the nD field data)

  • fieldmap_dim (int) – dimension of the field map, 1, 2, 3 for 1D, 2D and 3D field maps in TraceWin format

  • x_on_axis (float) – Field is given for x=x_on_axis [default 0]

  • y_on_axis (float) – Field is given for y=y_on_axis [default 0]

Returns

  • returns a 2D array containing the z coordinates and the field on axis in the z direction

  • Take a 2D or 3D field map as a 1D numpy array (as from TraceWin) in MV/m,

  • dimension of the field map,

  • returns the field on-axis in the z direction

  • example

  • field_on_axis(header, field, 3)

ess.fieldmap.field_on_axis_from_file(file_path, fieldmap_dim: int, file_type: str)[source]
Parameters

  • file_path (string) – name of the field map file including its path and extension

  • fieldmap_dim (int) – dimension of the field map, 1, 2, 3 for 1D, 2D and 3D field maps in TraceWin format

  • file_type (string) – ‘b’ for binary and ‘a’ for ascii field map files.

Returns

  • returns a 2D array containing the z coordinates and the field on axis in the z direction

  • Take a 2D or 3D fieldmap as a 1D numpy array (as from TraceWin) in MV/m,

  • dimension of the fieldmap,

  • returns the field on-axis in the z direction

  • example

  • field_on_axis_from_file(‘Data/FM/HB_W_coupler.edz’, 3, ‘b’)

ess.fieldmap.read_fieldmap(filepath: str, fieldmap_dim: int, file_type: str)[source]
Parameters

  • filepath (string) – path to the binary fieldmap file including the path, file name and extension

  • fieldmap_dim (int) – dimension of the fieldmap, 1, 2 and 3 for 1D, 2D and 3D TraceWin formatted fieldmap

  • file_type (str) – ‘b’ for binary and ‘a’ for ascii fieldmap files.

Returns

  • a list containing Header and Field

  • Header (1D array of size 3, 5, 9 (for 1D, 2D and 3D fieldmaps)) – TraceWin fieldmap header info

  • Field (1D numpy array containing the nD field data)

ess.fieldmap.save_to_ascii(Header, Field, output_filepath: str)[source]

Saves a TraceWin readable ASCII file

Parameters

  • Header (array like) – 1D array of size (3, 5 or 9) for 1D, 2D or 3D fieldmap header info, TraceWin format

  • Field (array like) – 1D array of size Nz fieldmap containing field data

  • output_filepath (string) – path to the output file

ess.fieldmap.uniform_mesh(mesh: list)[source]
Parameters

mesh (list) – a 1D array which is the coordinate values of the field

Returns

a tuple containing a boolean (if the mesh is uniform or not), mesh_size (average to reduce the effect of floating point error), and the number of steps from min to max (n numbers would result in n-1)

Return type

tuple

ess.fieldmap.unify_grid_size(old_x: list, old_y: list, new_x: list, kind='linear', save_to_file=None)[source]

Takes a mesh as x values and the corresponding values of a function. creates a spline interpolation for those data sets. Using a new_x it returns the correcposnding new_y. Could be used to convert an irregular mesh to a regular mesh or to increase the number of mesh points

Parameters

  • old_x (list,)

  • old_y (list,)

  • new_x (list)

  • kind (str) – An integer specifying the order of the spline interpolator to use. Default is ‘linear’.

    • ‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’: refer to a spline interpolation of zeroth, first, second or third order

    • ‘previous’ or ‘next’: return the previous or next value of the point

  • save_to_file (str) – If given, file name where this should be saved.

Returns

new_y

Return type

list