Skip to content

Nickname Setting

Overview¤

A module for handling the EFIT tree nickname passed in the RetrievalSettings class. DisruptionPy uses the nickname setting to determine which MDSplus EFIT tree to get data from.

This module defines the abstract class NicknameSetting that can have subclasses passed as the efit_nickname_setting parameter to the RetrievalSettings class. It also provides built-in classes and mappings to easily set the nickname for data retrieval for common use cases.

Usage¤

Currently, these are the options that can be passed to the efit_nickname_setting parameter in RetrievalSettings:

  • An instance of a subclass of NicknameSetting
  • A string identifier in the _nickname_setting_mappings dictionary: 
    _nickname_setting_mappings: Dict[str, NicknameSetting] = {
    "default": DefaultNicknameSetting(),
    "disruption": DisruptionNicknameSetting(),
    # deprecated
    "analysis": DefaultNicknameSetting(),
    "disruption_warning": DisruptionNicknameSetting(),
}
  • A dictionary mapping tokamak type strings to the desired NicknameSetting for that tokamak. E.g. {'cmod': 'efit'}. Currently supported tokamak type strings are: "cmod", "d3d"

Built-in Implemenations¤

This module provides classes for handling nickname settings, which are used to resolve MDSplus tree names for various tokamaks.

disruption_py.settings.nickname_setting.StaticNicknameSetting ¤

Bases: NicknameSetting

Static nickname setting that always returns a fixed tree name.

PARAMETER DESCRIPTION
tree_name

The tree name to be returned.

TYPE: str

Source code in disruption_py/settings/nickname_setting.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
class StaticNicknameSetting(NicknameSetting):
    """
    Static nickname setting that always returns a fixed tree name.

    Parameters
    ----------
    tree_name : str
        The tree name to be returned.
    """

    def __init__(self, tree_name: str):
        """
        Initialize StaticNicknameSetting with a fixed tree name.

        Parameters
        ----------
        tree_name : str
            The fixed tree name.
        """
        self.tree_name = tree_name

    def _get_tree_name(self, params: NicknameSettingParams) -> str:
        """
        Return the static tree name.

        Parameters
        ----------
        params : NicknameSettingParams
            Parameters needed to determine the nickname.

        Returns
        -------
        str
            The fixed tree name.
        """
        return self.tree_name

__init__ ¤

__init__(tree_name: str)
PARAMETER DESCRIPTION
tree_name

The fixed tree name.

TYPE: str

Source code in disruption_py/settings/nickname_setting.py 
160
161
162
163
164
165
166
167
168
169
def __init__(self, tree_name: str):
    """
    Initialize StaticNicknameSetting with a fixed tree name.

    Parameters
    ----------
    tree_name : str
        The fixed tree name.
    """
    self.tree_name = tree_name

_get_tree_name ¤

_get_tree_name(params: NicknameSettingParams) -> str

Return the static tree name.

PARAMETER DESCRIPTION
params

Parameters needed to determine the nickname.

TYPE: NicknameSettingParams

RETURNS DESCRIPTION
str

The fixed tree name.
Source code in disruption_py/settings/nickname_setting.py 
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def _get_tree_name(self, params: NicknameSettingParams) -> str:
    """
    Return the static tree name.

    Parameters
    ----------
    params : NicknameSettingParams
        Parameters needed to determine the nickname.

    Returns
    -------
    str
        The fixed tree name.
    """
    return self.tree_name

disruption_py.settings.nickname_setting.DefaultNicknameSetting ¤

Bases: NicknameSetting

Nickname setting to resolve the '_efit_tree' nickname to the default EFIT tree.

Source code in disruption_py/settings/nickname_setting.py 
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
class DefaultNicknameSetting(NicknameSetting):
    """
    Nickname setting to resolve the '_efit_tree' nickname to the default EFIT tree.
    """

    def __init__(self):
        """
        Initialize with default tree names for specific tokamaks.
        """
        self.tokamak_overrides = {
            Tokamak.CMOD: StaticNicknameSetting("analysis")._get_tree_name,
            Tokamak.D3D: StaticNicknameSetting("efit01")._get_tree_name,
        }

    def _get_tree_name(self, params: NicknameSettingParams) -> str:
        """
        Raise error if tokamak override is not found.

        Parameters
        ----------
        params : NicknameSettingParams
            Parameters needed to determine the nickname.
        """
        raise NotImplementedError(
            f"{self.__class__.__name__} is not implemented for tokamak {params.tokamak}."
        )

__init__ ¤

__init__()
Source code in disruption_py/settings/nickname_setting.py 
193
194
195
196
197
198
199
200
def __init__(self):
    """
    Initialize with default tree names for specific tokamaks.
    """
    self.tokamak_overrides = {
        Tokamak.CMOD: StaticNicknameSetting("analysis")._get_tree_name,
        Tokamak.D3D: StaticNicknameSetting("efit01")._get_tree_name,
    }

_get_tree_name ¤

_get_tree_name(params: NicknameSettingParams) -> str

Raise error if tokamak override is not found.

PARAMETER DESCRIPTION
params

Parameters needed to determine the nickname.

TYPE: NicknameSettingParams

Source code in disruption_py/settings/nickname_setting.py 
202
203
204
205
206
207
208
209
210
211
212
213
def _get_tree_name(self, params: NicknameSettingParams) -> str:
    """
    Raise error if tokamak override is not found.

    Parameters
    ----------
    params : NicknameSettingParams
        Parameters needed to determine the nickname.
    """
    raise NotImplementedError(
        f"{self.__class__.__name__} is not implemented for tokamak {params.tokamak}."
    )

disruption_py.settings.nickname_setting.DisruptionNicknameSetting ¤

Bases: NicknameSetting

Nickname setting to resolve the '_efit_tree' nickname to the disruption EFIT tree.

Source code in disruption_py/settings/nickname_setting.py 
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
class DisruptionNicknameSetting(NicknameSetting):
    """
    Nickname setting to resolve the '_efit_tree' nickname to the disruption EFIT tree.
    """

    def __init__(self):
        """
        Initialize with tokamak-specific overrides for disruption trees.
        """
        self.tokamak_overrides = {
            Tokamak.CMOD: self._cmod_nickname,
            Tokamak.D3D: self._d3d_nickname,
        }

    def _d3d_nickname(self, params: NicknameSettingParams) -> str:
        """
        Get the disruption EFIT tree name for D3D.

        Parameters
        ----------
        params : NicknameSettingParams
            Parameters needed to determine the nickname.

        Returns
        -------
        str
            The resolved EFIT tree name.
        """
        if params.disruption_time is None:
            # TODO: some DIII-D shots have a disruption efit tree, but no disruption time.
            return DefaultNicknameSetting().get_tree_name(params)
        efit_trees = params.database.query(
            "select tree from code_rundb.dbo.plasmas where "
            f"shot = {params.shot_id} and runtag = 'DIS' and deleted = 0 order by idx",
            use_pandas=False,
        )
        if len(efit_trees) == 0:
            return DefaultNicknameSetting().get_tree_name(params)
        efit_tree = efit_trees[-1][0]
        return efit_tree

    def _cmod_nickname(self, params: NicknameSettingParams) -> str:
        """
        Get the disruption EFIT tree name for CMOD.

        Parameters
        ----------
        params : NicknameSettingParams
            Parameters needed to determine the nickname.

        Returns
        -------
        str
            The resolved EFIT tree name.
        """
        if params.disruption_time is None:
            return DefaultNicknameSetting().get_tree_name(params)
        return "efit18"

    def _get_tree_name(self, params: NicknameSettingParams) -> str:
        """
        Raise error if tokamak override is not found.

        Parameters
        ----------
        params : NicknameSettingParams
            Parameters needed to determine the nickname.
        """
        raise NotImplementedError(
            f"{self.__class__.__name__} is not implemented for tokamak {params.tokamak}."
        )

__init__ ¤

__init__()
Source code in disruption_py/settings/nickname_setting.py 
221
222
223
224
225
226
227
228
def __init__(self):
    """
    Initialize with tokamak-specific overrides for disruption trees.
    """
    self.tokamak_overrides = {
        Tokamak.CMOD: self._cmod_nickname,
        Tokamak.D3D: self._d3d_nickname,
    }

_cmod_nickname ¤

_cmod_nickname(params: NicknameSettingParams) -> str

Get the disruption EFIT tree name for CMOD.

PARAMETER DESCRIPTION
params

Parameters needed to determine the nickname.

TYPE: NicknameSettingParams

RETURNS DESCRIPTION
str

The resolved EFIT tree name.
Source code in disruption_py/settings/nickname_setting.py 
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
def _cmod_nickname(self, params: NicknameSettingParams) -> str:
    """
    Get the disruption EFIT tree name for CMOD.

    Parameters
    ----------
    params : NicknameSettingParams
        Parameters needed to determine the nickname.

    Returns
    -------
    str
        The resolved EFIT tree name.
    """
    if params.disruption_time is None:
        return DefaultNicknameSetting().get_tree_name(params)
    return "efit18"

_d3d_nickname ¤

_d3d_nickname(params: NicknameSettingParams) -> str

Get the disruption EFIT tree name for D3D.

PARAMETER DESCRIPTION
params

Parameters needed to determine the nickname.

TYPE: NicknameSettingParams

RETURNS DESCRIPTION
str

The resolved EFIT tree name.
Source code in disruption_py/settings/nickname_setting.py 
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
def _d3d_nickname(self, params: NicknameSettingParams) -> str:
    """
    Get the disruption EFIT tree name for D3D.

    Parameters
    ----------
    params : NicknameSettingParams
        Parameters needed to determine the nickname.

    Returns
    -------
    str
        The resolved EFIT tree name.
    """
    if params.disruption_time is None:
        # TODO: some DIII-D shots have a disruption efit tree, but no disruption time.
        return DefaultNicknameSetting().get_tree_name(params)
    efit_trees = params.database.query(
        "select tree from code_rundb.dbo.plasmas where "
        f"shot = {params.shot_id} and runtag = 'DIS' and deleted = 0 order by idx",
        use_pandas=False,
    )
    if len(efit_trees) == 0:
        return DefaultNicknameSetting().get_tree_name(params)
    efit_tree = efit_trees[-1][0]
    return efit_tree

_get_tree_name ¤

_get_tree_name(params: NicknameSettingParams) -> str

Raise error if tokamak override is not found.

PARAMETER DESCRIPTION
params

Parameters needed to determine the nickname.

TYPE: NicknameSettingParams

Source code in disruption_py/settings/nickname_setting.py 
275
276
277
278
279
280
281
282
283
284
285
286
def _get_tree_name(self, params: NicknameSettingParams) -> str:
    """
    Raise error if tokamak override is not found.

    Parameters
    ----------
    params : NicknameSettingParams
        Parameters needed to determine the nickname.
    """
    raise NotImplementedError(
        f"{self.__class__.__name__} is not implemented for tokamak {params.tokamak}."
    )

Custom Implementations¤

Custom implementations of a nickname setting must inherit from the NicknameSetting abstract class, implementing the abstract methods.

This module provides classes for handling nickname settings, which are used to resolve MDSplus tree names for various tokamaks.

disruption_py.settings.nickname_setting.NicknameSetting ¤

Bases: ABC

Abstract base class for nickname settings to resolve tree names for MDSPlus data.

METHOD DESCRIPTION
get_tree_name

Resolve the tree name based on the given params.
Source code in disruption_py/settings/nickname_setting.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
class NicknameSetting(ABC):
    """
    Abstract base class for nickname settings to resolve tree names for MDSPlus data.

    Methods
    -------
    get_tree_name(params)
        Resolve the tree name based on the given params.
    """

    def get_tree_name(self, params: NicknameSettingParams) -> str:
        """
        Resolve the MDSPlus tree name using the provided params.

        Parameters
        ----------
        params : NicknameSettingParams
            The parameters needed to determine the tree name.

        Returns
        -------
        str
            The resolved MDSPlus tree name.
        """
        if hasattr(self, "tokamak_overrides"):
            if params.tokamak in self.tokamak_overrides:
                return self.tokamak_overrides[params.tokamak](params)
        return self._get_tree_name(params)

    @abstractmethod
    def _get_tree_name(self, params: NicknameSettingParams) -> str:
        """
        Abstract method for resolving the MDSPlus tree name.

        Parameters
        ----------
        params : NicknameSettingParams
            The parameters required to retrieve the tree name.

        Returns
        -------
        str
            The resolved MDSPlus tree name.
        """

_get_tree_name abstractmethod ¤

_get_tree_name(params: NicknameSettingParams) -> str

Abstract method for resolving the MDSPlus tree name.

PARAMETER DESCRIPTION
params

The parameters required to retrieve the tree name.

TYPE: NicknameSettingParams

RETURNS DESCRIPTION
str

The resolved MDSPlus tree name.
Source code in disruption_py/settings/nickname_setting.py 
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
@abstractmethod
def _get_tree_name(self, params: NicknameSettingParams) -> str:
    """
    Abstract method for resolving the MDSPlus tree name.

    Parameters
    ----------
    params : NicknameSettingParams
        The parameters required to retrieve the tree name.

    Returns
    -------
    str
        The resolved MDSPlus tree name.
    """

get_tree_name ¤

get_tree_name(params: NicknameSettingParams) -> str

Resolve the MDSPlus tree name using the provided params.

PARAMETER DESCRIPTION
params

The parameters needed to determine the tree name.

TYPE: NicknameSettingParams

RETURNS DESCRIPTION
str

The resolved MDSPlus tree name.
Source code in disruption_py/settings/nickname_setting.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def get_tree_name(self, params: NicknameSettingParams) -> str:
    """
    Resolve the MDSPlus tree name using the provided params.

    Parameters
    ----------
    params : NicknameSettingParams
        The parameters needed to determine the tree name.

    Returns
    -------
    str
        The resolved MDSPlus tree name.
    """
    if hasattr(self, "tokamak_overrides"):
        if params.tokamak in self.tokamak_overrides:
            return self.tokamak_overrides[params.tokamak](params)
    return self._get_tree_name(params)

disruption_py.settings.nickname_setting.NicknameSettingParams dataclass ¤

Parameters passed to nickname trees for resolving tree nicknames.

ATTRIBUTE DESCRIPTION
shot_id

The shot ID for which to resolve nicknames.

TYPE: int

mds_conn

MDSConnection object for accessing MDSPlus data.

TYPE: MDSConnection

database

Database connection for querying tokamak shot data.

TYPE: ShotDatabase

disruption_time

The time of the disruption in seconds.

TYPE: float

tokamak

The tokamak for which results are being processed.

TYPE: Tokamak

logger

Logger for logging relevant messages.

TYPE: Logger

Source code in disruption_py/settings/nickname_setting.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
@dataclass
class NicknameSettingParams:
    """
    Parameters passed to nickname trees for resolving tree nicknames.

    Attributes
    ----------
    shot_id : int
        The shot ID for which to resolve nicknames.
    mds_conn : MDSConnection
        MDSConnection object for accessing MDSPlus data.
    database : ShotDatabase
        Database connection for querying tokamak shot data.
    disruption_time : float
        The time of the disruption in seconds.
    tokamak : Tokamak
        The tokamak for which results are being processed.
    logger : Logger
        Logger for logging relevant messages.
    """

    shot_id: int
    mds_conn: MDSConnection
    database: ShotDatabase
    disruption_time: float
    tokamak: Tokamak
    logger: Logger