Overview

What is a Physics Method?

In DisruptionPy, physics methods are methods that produce tabular data in a standardized time base. Physics methods must take a single argument params that is an instance of PhysicsMethodParams.

Built-in Physics Methods

While you can define your own, existing built-in physics methods are defined inside of the disruption_py.machine package.

For more information on available methods please see the built-in method documentation pages:

• CMod Physics Methods
• DIII-D Physics Methods

Custom Physics Methods

Users of DisruptionPy can create their own custom physics methods by adding the @physics_method decorator to a method. These custom physics methods can then be passed as the custom_physics_methods parameter in RetrievalSettings and their results will be included alongside those returned by the built-in methods. See Physics Method Decorators for more details on decorators.

Physics methods structure

All parametrized methods passed to get_shots_data will be called once for every shot retrieved. Decorated methods may call other decorated methods, however execution order is not guaranteed as calls will be reordered to minimize resource usage based on the physics_method decorator.

PARAMETER	DESCRIPTION
params	Parameters passed by disruption_py to the decorated method that should be used to help retrieve the shot data from MDSplus. TYPE: PhysicsMethodParams

RETURNS	DESCRIPTION
dict	Dictionary containing the results of the decorated method, with each returned parameter being a key-value pair. Each of the dictionary's values should be the same length as the timebase (params.times).

Walkthrough

The steps for creating a custom physics method are as follows:

1. Create a function that takes an argument named params of type PhysicsMethodParams and returns a Python dictionary. The method must be decorated with the physics_method decorator. The arguments passed to the decorator are important for DisruptionPy to run efficiently. See physics_method for more details about available arguments.

   from disruption_py.core.physics_method.params import PhysicsMethodParams
   from disruption_py.core.physics_method.decorator import physics_method
   
   @physics_method(...)
   def ***_method(params: PhysicsMethodParams) -> dict:
       ...
   

2. To retrieve data from MDSplus use the params (PhysicsMethodParams) object. It contains many useful attributes, among which are the following:

   • params.shot_id: the shot id of the shot for which data is being retrieved.
   • params.mds_conn: a wrapper around the MDSplus connection for the process, that makes it easier to get data for a shot. See MDSConnection for details.
   • params.times: the timebase of the shot for which data is being retrieved as a NumPy array of times.

Shot Data Request Examples

Kappa Area Parameter in C-Mod

# pylint: disable=duplicate-code
@physics_method(columns=["custom_kappa_area"], tokamak=Tokamak.CMOD)
def get_custom_kappa_area(params: PhysicsMethodParams):
    aminor = params.mds_conn.get_data(
        r"\efit_aeqdsk:aminor", tree_name="_efit_tree", astype="float64"
    )
    area = params.mds_conn.get_data(
        r"\efit_aeqdsk:area", tree_name="_efit_tree", astype="float64"
    )
    times = params.mds_conn.get_data(
        r"\efit_aeqdsk:time", tree_name="_efit_tree", astype="float64"
    )

    # Ensure aminor and area are not 0 or less than 0
    aminor[aminor <= 0] = 0.001
    area[area <= 0] = 3.14 * 0.001**2
    return {
        "custom_kappa_area": interp1(times, area / (np.pi * aminor**2), params.times)
    }

Warning

When two output columns have the same name, the column that appears in the final dataset is not guaranteed. This issue will be fixed in the near future.

Running Physics Methods

Users can use a number of built-in physics methods and/or create their own methods.

For a physics method to be run after calling get_shots_data it must meet the following conditions:

1. The method must either:

   • be included inside of the disruption_py.machine.method_holders.py list (built-in method)
   • be included inside of the custom_physics_methods argument of RetrievalSettings when getting shot data.

2. The method must have the physics_method decorator with its tokamak parameter either not set or set to the tokamak that you are retrieving data from.

3. The method is included to run via either the run_methods or run_columns parameters of the shot settings.

   • To be included via run_methods, the method name must be listed inside of run_methods
   • To be included via run_columns, the method must have a column list in the columns parameter of the physics_method decorator that is included in run_columns
   • If neither run_methods nor run_columns is specified, all built-in methods will be run

Once all designated methods have been collected, DisruptionPy optimizes their execution order to minimize resource usage by using the information supplied in the physics_method decorator. Once reordering is complete, the methods are run.

disruption_py.core.physics_method.params

Module for defining parameters used in physics methods for DisruptionPy.

PhysicsMethodParams dataclass

Holder for useful variables for the physics methods like an MDSplus connection and the timebase for the data.

Source code in disruption_py/core/physics_method/params.py

@dataclass
class PhysicsMethodParams:
    """
    Holder for useful variables for the physics methods like an MDSplus connection
    and the timebase for the data.
    """

    shot_id: int
    tokamak: Tokamak
    disruption_time: float
    mds_conn: MDSConnection
    times: np.ndarray

    def __post_init__(self):
        self.logger = shot_msg_patch(logger, self.shot_id)

    cached_results: Dict[str, Any] = field(default_factory=dict)

    @property
    def disrupted(self) -> bool:
        """
        Check if the disruption time is set.

        Returns
        -------
        bool
            True if disruption time is not None, False otherwise.
        """
        return self.disruption_time is not None

    def cleanup(self) -> None:
        """
        Clean up resources used by the physics method parameters.
        """
        self.mds_conn.cleanup()
        self.times = None
        self.cached_results.clear()

    def to_coords(self) -> Dict[str, Tuple[str, np.ndarray]]:
        """
        Create a dictionary of coordinates based on the parameters.

        Returns
        -------
        Dict[str, Tuple[str, np.ndarray]]
            A dictionary with `shot` and `time` as coordinates for dimension `idx`.
        """
        return to_tuple(
            data={
                "shot": len(self.times) * [self.shot_id],
                "time": self.times,
            },
            dim="idx",
        )

disrupted property

disrupted: bool

Check if the disruption time is set.

RETURNS	DESCRIPTION
bool	True if disruption time is not None, False otherwise.

cleanup

cleanup() -> None

Clean up resources used by the physics method parameters.

Source code in disruption_py/core/physics_method/params.py

def cleanup(self) -> None:
    """
    Clean up resources used by the physics method parameters.
    """
    self.mds_conn.cleanup()
    self.times = None
    self.cached_results.clear()

to_coords

to_coords() -> Dict[str, Tuple[str, np.ndarray]]

Create a dictionary of coordinates based on the parameters.

RETURNS	DESCRIPTION
Dict[str, Tuple[str, ndarray]]	A dictionary with shot and time as coordinates for dimension idx.

Source code in disruption_py/core/physics_method/params.py

def to_coords(self) -> Dict[str, Tuple[str, np.ndarray]]:
    """
    Create a dictionary of coordinates based on the parameters.

    Returns
    -------
    Dict[str, Tuple[str, np.ndarray]]
        A dictionary with `shot` and `time` as coordinates for dimension `idx`.
    """
    return to_tuple(
        data={
            "shot": len(self.times) * [self.shot_id],
            "time": self.times,
        },
        dim="idx",
    )