importExternalField.py

This analyzer facilitates importing an external field from a CSV file and interpolating those values of that field onto the XSim simulation grid. In order to use an external field in XSim, one must make sure that the field values are on the same computational grid as all of the other simulation fields. This analyzer utility addresses that by reading the external field values and interpolating those values to the grid. The extents of the simulation grid must be known prior to running this analyzer, and if the simulation grid changes the analyzer utility should be run again. This analyzer is particularly helpful for importing external magnetic field data.

This analyzer utility only works for external field data that is 2- or 3-dimensional. If you have 1-dimensional data, then it will need to be extended to 2-dimensional prior to running the analyzer utility.

This analyzer utility works for scalar and vector fields, but typically will be used for vector fields. The field component values for any simulation grid points that are outside of the convex kern of the external field data are set to zero.

Entries in the CSV file should be numerical or convertable to numerical values, except for the header lines that are skipped. There should be no empty lines in the file after the header lines.

Interpolation of the external field data to the XSim computational mesh can be very time consuming, especially for very large data sets. For this reason, the triangulation is saved the first time that this analyzer utility is exectuted. There is an optional parameter (see below) that enables one to read in the saved interpolators (called a pickle file) without having to recompute them in the case that the XSim simulation grid changes.

This analyzer replaces convertHFSS2VsHdf5 and convertCSV2VsHdf5 as it is both more general, and it interpolates the external field onto the XSim simulation grid.

-s <simname>, --simulationName=<simname>

(string, required)

<simname> is the name of the simulation to be analyzed. The file extension should NOT be included in this text field.

-f, --file_name

(string, required)

The name of the CSV file containing the external field values.

-sr, --skip_rows

(int, optional, default = 0)

The number of (header) rows at the top of the CSV file to skip when reading the file.

-su, --spatial_units

(float, optional, default = 1.0)

The units of the spatial dimensions in the CSV data relative to meters. Eg. 0.001 is milimeters.

-sd, --spatial_dims

(string, optional, default = “(0,1,2)”)

The columns corresponding to the spatial dimensions, as indexes as a parend, quoted, comma delimited list. Eg. if column 0 is X, column 1 is Y, and column 2 is Z, then –spatial_dims=”(0,1,2)”. If column 0 is R and column 1 is Z, then –spatial_dims=”(1,0)”. Note that in XSim cylindrical coordinates the axes are ordered as (Z,R,Phi).

-fu, --field_units

(float, optional, default = 1.0)

The units of the field values in the CSV data relative to Tesla. Eg, 10000 is Gauss.

-fd, --field_dims

(string, optional, default = “(3,4,5)”)

The columns corresponding to the spatial dimensions, as indexes as a parend, quoted, comma delimited list. Eg. if column 3 is Bx, column 4 is By, and column 5 is Bz, then –field_dims=”(3,4,5)”. If column 2 is Br, column 3 is Bz, and column 4 is Bphi, then –field_dims=”(3,2,4)”. Note that in XSim cylindrical coordinates the axes are ordered as (Z,R,Phi).

-c, --centering

(string, optional, default = “none”)

The type of data centering of the XSim field. One of none, edge, or face. For magnetic fields, typically use “face”.

-lc, --lower_coords

(string, required)

The lower coordinates of the XSim target field as a parend, quoted, comma-delimited list in meters. eg. “(-.8,0.3,0.3)”.

-uc, --upper_coords

(string, required)

The upper coordinates of the XSim target field as a parend, quoted, comma-delimited list in meters. eg. “(.9,2.1,1.5)”.

-nc, --num_cells

(string, required)

The number of cells of the computational mesh of the target field as a quoted, comma-delimited list. eg. “(128,512,512)”.

-pkl, --pickle_file

(string, optional)

Optional name of a file containing saved interpolators. Useful for re-running this utility without having to re-compute the triangularization.

-Z, --compMajorC

(flag)

The indexing order for written datasets. If checked, use “compMajorC”. If unchecked, use the default “compMinorC”

-w, --overwrite

(flag)

Whether a dataset or group should be overwritten if it already exists

Output

This analyzer utility creates a VizSchema-compliant file called <simname>_<output_field_name>_0.vsh5 that contains the interpolated external field on the XSim simulation grid. It also saves a VizSchema-compliant file called <simname>_<output_field_name>Mag_0.vsh5 that contains the magnitude of the field on the XSim simulation grid. Both fields are visualize-able in Composer.