omfit-omas-utils 2020.12.2.22.59
omfit_omas_utils
Requires Python: >=3.6

**OMAS_UTILS** files used as part of the OMFIT project: https://omfit.io/

Provides:
=========
* add_generic_OMFIT_info_to_ods
* add_experiment_info_to_ods
* ensure_consistent_experiment_info
* setup_hardware_overlay_cx
* toray_to_omas
* nubeam_to_omas
* add_hardware_to_ods
* multi_efit_to_omas
* pf_coils_to_ods
* make_sample_ods
* transp_ic_to_omas
* setup_magnetics_hardware_description_general
* select_mag_probe_template
* get_shape_control_points
* setup_position_control_hardware_description_general
* setup_pulse_schedule_hardware_description_general
* classify_ods_eq_topology
* get_strike_point
* OmasUtilsBadInput
* orthogonal_distance

Requires:
=========
* fortranformat>=0.2
* matplotlib>=3.1,!=3.2.1,!=3.2.2
* numpy>=1.12
* omas>=0.67.0
* scipy>=1.0
* uncertainties>=3
* xarray>=0.10.8
* omfit_mds==2020.12.2.22.59
* omfit_data==2020.12.2.22.59
* omfit_eqdsk==2020.12.2.22.59
* omfit_ascii==2020.12.2.22.59
* omfit_path==2020.12.2.22.59
* omfit_nc==2020.12.2.22.59
* omfit_namelist==2020.12.2.22.59
* omfit_error==2020.12.2.22.59
* omfit_commonclasses==2020.12.2.22.59

Authors:
=========
https://omfit.io/contributors.html

Documentation:
==============
add_generic_OMFIT_info_to_ods
-----------------------------

    This function will fill in information in the ``ids_properties``
    and ``code`` section of the input ``ods`` and return the updated ``ods``

    :param ods: An omas ods instance

    :param root: An OMFITmodule, from which to extract the commit

    :returns: The updated ods
    

add_experiment_info_to_ods
--------------------------

    This function will fill in information in the `info` about the machine/pulse

    :param ods: An omas ods instance

    :param root: An OMFITmodule, from which to extract the machine/pulse info

    :returns: The updated ods
    

ensure_consistent_experiment_info
---------------------------------

    Ensures that the ODS, device, and shot are consistent

    If machine or pulse are not set, they are set to the provided device / shot.
    If they are set but inconsistent, AssertionError is raised.

    :param ods: ODS instance

    :param device: str

    :param shot: int
    

setup_hardware_overlay_cx
-------------------------

    Sets up an OMAS ODS so that it can power a cross section view with diagnostic/hardware overlays. This involves
    looking up and writing locations of various hardware to the ODS.

    :param device: string
        Which tokamak?

    :param pulse: int
        Which pulse number? Used for gathering equilibrium and for looking up hardware configuration as it
        could vary with time.

    :param time: int or float array [optional]
        Time (ms) within the pulse, used for looking up equilibrium only
        If None and no gEQDSKs, try to get all times from MDSplus

    :param efitid: string
        EFIT SNAP file or ID tag in MDS plus: used for looking up equilibrium only

    :param geqdsk: OMFITgeqdsk instance (optional)
        Provides EFIT instead of lookup using device, pulse, time, efitid. efitid will be ignored completely. device
        and pulse will still be used to look up hardware configuration. time might be used. Providing inconsistent
        data may produce confusing plots.

    :param overwrite: bool
        Flag indicating whether it is okay to overwrite locations if they already exist in ODS

    :param default_load: bool
        Default action to take for loading a system. For example, \**kw lets you explicitly set gas_injection=False to
        prevent calling setup_gas_injection_hardware_description. But for systems which aren't specified, the default
        action (True/False to load/not load) is controlled by this parameter.

    :param minimal_eq_data: bool
        Skip loading all the equilibrium data needed to recreate GEQDSK files and only get what's needed for plots.

    :param \**kw: keywords dictionary
        Disable gathering/setup of data for individual hardware systems by setting them to False using their names
        within IMAS.
        For example: gas_injection=False will prevent the call to setup_gas_injection_hardware_description().

    :return: OMAS ODS instance containing the data you need to draw a cross section w/ diagnostic/hardware overlays.
    

toray_to_omas
-------------

    Given 3 ECH UFILEs (azimuthal angle, polar angle, and power), return an ODS with the launcher info filled out

    :param ech_nml: A TORAY namelist

    :param uf_azi: An ECH Ufile containing the azimuthal angle

    :param uf_pol: An ECH Ufile containing the polar angle

    :param uf_pow: An ECH Ufile containing the power

    :param ods: An existing ODS, to which to add the launcher info from the Ufiles

    :param root: An OMFITmodule instance (for experiment and generic OMFIT info)
    

nubeam_to_omas
--------------

    Given a NUBEAM namelist and UFILE, return an ODS with the beam info filled out

    :param nb_nml: A NUBEAM namelist

    :param nb_uf: A NUBEAM Ufile

    :param ods: An existing ODS, to which to add the beam info from the namelist and Ufile

    :param root: An OMFITmodule instance (for experiment and generic OMFIT info)
    

add_hardware_to_ods
-------------------

    Adds a single hardware system's info to an ODS (operates in place)

    :param ods: ODS instance

    :param device: string

    :param pulse: int

    :param hw_sys: string

    :param overwrite: bool

    :return: updated ods
    

multi_efit_to_omas
------------------

    Writes equilibrium data from MDSplus to ODS

    :param device: string

    :param pulse: int

    :param efitid: string

    :param ods: ODS instance
        A New ODS will be created if this is None

    :param minimal: bool
        Only gather and add enough data to run a cross-section plot

    :param aeqdsk_time_diff_tol: float
        Time difference in ms to allow between GEQDSK and AEQDSK time bases, in case they don't match exactly.
        GEQDSK slices where the closest AEQDSK time are farther away than this will not have AEQDSK data.

    :param \**kw: Additional keywords to read_basic_eq_from_mds()
        But not the quantities to gather as those are set explicitly in this function.

    :return: ODS instance
        The edit is done in-place, so you don't have to catch the output if you supply the input ODS
        On fail: empty ODS is returned
    

pf_coils_to_ods
---------------

    Transfers poloidal field coil geometry data from a standard format used by efitviewer to ODS.

    WARNING: only rudimentary identifies are assigned.
    You should assign your own identifiers and only rely on this function to assign numerical geometry data.

    :param ods: ODS instance
        Data will be added in-place
    :param coil_data: 2d array
        coil_data[i] corresponds to coil i. The columns are R (m), Z (m), dR (m), dZ (m), tilt1 (deg), and tilt2 (deg)
        This should work if you just copy data from iris:/fusion/usc/src/idl/efitview/diagnoses/<device>/*coils*.dat
        (the filenames for the coils vary)
    :return: ODS instance
    

make_sample_ods
---------------

    Generates an ODS with some minimal test data, including a sample equilibrium and at least one hardware system
    :param device: string
    :param shot: int
    :param efitid: string
    :return: ODS
    

transp_ic_to_omas
-----------------

    Convert the TRANSP input namelist, tr_in, to omas

    :param tr_in: A TRANSP input namelist (TR.DAT)

    :param ods: An existing ODS object to update with IC antenna/power info

    :param uf_p: A ufile with power traces

    :param uf_f: A ufile with frequency traces

    :param root: An OMFITmodule instance (for experiment and generic OMFIT info)
    

setup_magnetics_hardware_description_general
--------------------------------------------

    Writes magnetic probe locations into ODS.

    :param ods: an OMAS ODS instance

    :param device: string
        Which tokamak?

    :param pulse: int

    :return: dict
        Information or instructions for follow up in central hardware description setup
    

select_mag_probe_template
-------------------------

    Selects and returns a magnetic probe information template. Used in chisquares plot.

    defaultVars parameters
    ----------------------
    :param device: string
        Which tokamak?

    :param shot: int
        Shot number used for looking up configuration in case it changed over time.

    :param templates: dict like [optional]
        dict or OMFITtree instance or similar containing templates. Within EFITtime, this is just root['TEMPLATES'].

    :return OMFITnamelist or None
        Returns a namelist with probe information (like R,Z coordinates, names, etc) if it can find one, otherwise None.
    

get_shape_control_points
------------------------

    Gathers shape control points describing targets for the plasma boundary to intersect and returns them

    :param dev: string
    :param sh: int
    :param times_: float array [optional]
        Times to use. If provided, interpolate data. If not, auto-assign using first valid segment.
    :param debug: bool
    :param debug_out: dict-like [optional]
    :return: tuple
        (
            t: 1d float array (nt): times in ms (actual times used)
            r: 2d float array (nt * nseg): R coordinate in m of shape control points. Unused points are filled with NaN.
            z: 2d float array (nt * nseg): Z coordinate in m of shape control points
            rx: 2d float array (nt * 2): R coordinate in m of X points (2nd one may be NaN)
            rz: 2d float array (nt * 2): Z of X-points. Order is [bottom, top]
            rptnames: list of strings (nseg) giving labels for describing ctrl pts
            zptnames: list of strings (nseg) giving labels for describing ctrl pts
            list of 1D bool arrays vs. t giving validity of outer bottom, inner bottom, outer top, inner top strike pts
        )
    

setup_position_control_hardware_description_general
---------------------------------------------------

    Loads DIII-D shape control data into the ODS
    :param ods: ODS instance
    :param shot: int
    :param device: string
        Only works for devices that have pointnames and other info specified. DIII-D should work.
    :param limiter_efit_id: string [optional]
    :param debug: bool
    :param debug_out: dict-like
        Catches debug output
    :return: dict
        Information or instructions for follow up in central hardware description setup
    

setup_pulse_schedule_hardware_description_general
-------------------------------------------------

    Sets up the pulse_schedule ODS, which holds control information

    This is a pretty broad category! Not all subsets are supported so far. Sorry.

    :param ods: ODS instance
    :param pulse: int
    :param device: string
    :return: dict
        Information or instructions for follow up in central hardware description setup
    

classify_ods_eq_topology
------------------------

    Figure out whether the shape is USN, LSN, or limited

    :param ods: ODS instance

    :param dn_tolerance: float
        Tolerance (in terms of normalized psi difference) for declaring a double null

    :return: 1D float array
        Flag indicating whether each equilibrium slice is LSN (-1), USN (+1), DN (0), or unknown/limited (np.NaN)
    

get_strike_point
----------------

    Identify a specific strike point and get its coordinates

    It's easy to just pick a strike point, or even find inner-upper or outer-lower, but
    identifying primary-outer or primary-inner is a little harder to do. It's not clear
    that there's any consistent ordering of strike points that would trivialize this
    process, so this function exists to do it for you.

    :param ods: ODS instance

    :param in_out: str
        'outer': try to get an outer strike point (default)
        'inner': try to get an inner strike point

    :param pri_sec: str
        'primary': try to get a strike point connected to the primary X-point (default)
        'secondary': try to get a strike point connected with a secondary X-point

    :return: tuple
        time: 1D float array (s)
        r_strike: 1D float array (m)
        z_strike: 1D float array (m)
    

OmasUtilsBadInput
-----------------
Bad inputs were used to a method in omfit_omas_utils.py

orthogonal_distance
-------------------

    Calculates the orthogonal distance from some point(s) to the LCFS

    Works by stepping along the steepest gradient until the LCFS is reached.

    :param ods: ODS instance
        A complete, top level ODS, or selection of time slices from equilibrium.
        That is, `ods['equilibrium']['time_slice']`, if `ods` is a top level ODS.

    :param r0: 1D float array
        R coordinates of the point(s) in meters.
        If grid=False, the arrays must have length matching the number of time slices in equilibrium.

    :param z0: 1D float array
        Z coordinates of the point(s) in meters.
        Length must match r0

    :param grid: bool
        Return coordinates on a time-space grid, assuming each point in R-Z is static and given a separate history.
        Otherwise (grid=False), assume one point is given & it moves in time, so return array will be 1D vs. time.

    :param time_range: 2 element numeric iterable [optional]
        Time range in seconds to use for filtering time_slice in ODS

    :param zf: float
        Zoom factor for upsampling the equilibrium first to improve accuracy. Ignored unless > 1.

    :param maxstep: float
        Maximum step size in m
        Restraining step size should prevent flying off the true path

    :param minstep: float
        Minimum step size in m
        Prevent calculation from taking too long by forcing a minimum step size

    :param maxsteps: int
        Maximum number of steps allowed in path tracing. Protection against getting stuck in a loop.

    :param debug: bool
        Returns a dictionary with internal quantities instead of an array with the final answer.

    :return: float array
        Length of a path orthogonal to flux surfaces from (r0, z0) to LCFS, in meters.
        If grid=True: 2D float array (time by points)
        If grid=False: a 1D float array vs. time