DMD Modes Tuner¶

class
ModesTuner
(dmds, in_place=False)[source]¶ Class for semiautomatic tuning of DMD modes.
This class generates a new instance from the instance passed to the constructor, and modifies that one whenever one of the tuning methods is called. Therefore there is no need to worry about subsequent unwanted changes in the given instance.
ModesTuner provides a simplified interface to the tuning functions
select_modes()
andstabilize_modes()
, but in order to have more control on what is happening (i.e. when to use inplace tuning, or to check which modes have been changed) you may prefer to use them instead. Parameters
dmds – One or more instances of DMD.
in_place (bool) – If True, this tuner works directly on the given DMD instance.

copy
()[source]¶ Returns a deep copy of the private DMD instance(s) that ModesTuner is working on. They are not going to be modified by subsequent calls to tuning methods, and therefore provide a secure “snapshot” to the DMD(s).
 Returns
A copy of the private DMD instance owned by ModesTuner, or a list of copies depending on the parameter received by the constructor of this instance.
 Return type
list or pydmd.DMDBase

get
()[source]¶ Returns the private DMD instance(s) that ModesTuner is working on. Be aware that those instances are the internal instances owned by ModesTuner, therefore they are going going to be modified by subsequent calls to tuning methods.
 Returns
The private DMD instance owned by ModesTuner, or a list of DMD instances depending on the parameter received by the constructor of this instance.
 Return type
list or pydmd.DMDBase

select
(criteria, nullify_amplitudes=False, **kwargs)[source]¶ Select the DMD modes by using the given criteria, which can be either a string or a function. You can choose prepacked criteria by passing one of the allowed string values for criteria. In this case you need to pass (as keyword arguments) the arguments needed to construct the criteria (see example below).
Allowed string values for criteria:
‘module_threshold’: Retain modes such that the module of the corresponding eigenvalue is included in the interval [low_threshold, up_threshold] (cfr.
ModesSelectors.threshold()
);‘stable_modes’: Retain modes such that the corresponding eigenvalue is not far from the unit circle (cfr.
ModesSelectors.stable_modes()
);‘integral_contribution’: Retain the first n modes in terms of integral contribution (cfr.
ModesSelectors.integral_contribution()
).
You might want to read the documentation of
ModesSelectors
in order to get detailed info regarding the behavior of each argument.Example:
>>> from pydmd.dmd_modes_tuner import ModesTuner >>> mtuner = ModesTuner(dmd) >>> mtuner.select('stable_modes', max_distance_from_unity_inside=1.e1, max_distance_from_unity_outside=1.e3)
 Parameters
criteria (str or callable) – Criteria used to select DMD modes. The allowed strings are module_threshold, stable_modes and integral_contribution. If criteria is a function it must take an instance of DMD as the only parameter.
nullify_amplitudes (bool) – If True, the amplitudes associated with DMD modes to be removed are set to 0, therefore the number of DMD modes remains constant. If False (default) DMD modes are actually removed, therefore the number of DMD modes in the instance decreases.
**kwargs – Parameters passed to the chosen criteria (if criteria is a string).
 Return ModesTuner
This instance of ModesTuner in order to allow chaining multiple operations.

stabilize
(inner_radius, outer_radius=inf)[source]¶ Stabilize modes in a circular sector of radius [inner_radius, outer_radius].
Stabilizing a mode means that the corresponding eigenvalue is divided by its module (i.e. normalized) in order to make the associated dynamic a trigonometric function with respect to the time (since the eigenvalue is projected on the unit circle). At the same time, the corresponding mode amplitude is multiplied by the former module of the eigenvalue, in order to “recover” the correctness of the result in the first time instants.
This approach may give better results in the prediction when one or more eigenvalues are strongly unstable (i.e. the corresponding DMD mode “explodes” several instants after the known time frame).
In order to stabilize an unbounded (above) circular sector, the parameter outer_radius should be set to np.inf (default).

subset
(indexes)[source]¶ Generate a temporary instance of ModesTuner which operates on a subset of the DMD instances held by this ModesTuner.
 Parameters
indexes (list) – List of indexes of the DMD instances to be put into the subset.
 Return ModesTuner
A ModesTuner which operates “in place” on the DMD instances held by the caller ModesTuner.
A module which contains several functions to tune (i.e. improve) DMD instances through the “manual” modification of DMD modes.

class
ModesSelectors
[source] Bases:
object
A container class which defines some static methods for prepacked modes selectors functions to be used in select_modes.
For instance, to select the first x modes by integral contributions:
Example:
>>> from pydmd.dmd_modes_tuner import ModesSelectors, select_modes >>> select_modes(dmd, ModesSelectors.integral_contribution(x))
Most private static methods in this class are “nonpartialized”, which means that they also take the parameters that characterize the selector. By contrast, public static method are ready mode selector, whose only parameter is the DMD instance on which that selector should be applied, and are the output of a call to functools.partial applied to a nonpartialized selector. This mechanism is employed to reduce the boilerplate code needed while applying a selector.

static
_compute_integral_contribution
(mode, dynamic)[source] Compute the integral contribution across time of the given DMD mode, given the mode and its dynamic, as shown in http://dx.doi.org/10.1016/j.euromechflu.2016.11.015
 Parameters
mode (numpy.ndarray) – The DMD mode.
dynamic (numpy.ndarray) – The dynamic of the given DMD mode, as returned by dmd.dynamics[mode_index].
 Return float
the integral contribution of the given DMD mode.

static
_integral_contribution
(dmd, n)[source] Nonpartialized function of the modes selector integral_contribution.
 Parameters
dmd (DMDBase) – An instance of DMDBase.
n (int) – The number of DMD modes to be selected.
 Return np.ndarray
An array of bool, where each “True” index means that the corresponding DMD mode is selected.

static
_stable_modes
(dmd, max_distance_from_unity_inside, max_distance_from_unity_outside)[source] Nonpartialized function of the modes selector stable_modes.
 Parameters
 Return np.ndarray
An array of bool, where each “True” index means that the corresponding DMD mode is selected.

static
_threshold
(dmd, low_threshold, up_threshold)[source] Nonpartialized function of the modes selector threshold.
 Parameters
 Return np.ndarray
An array of bool, where each “True” index means that the corresponding DMD mode is selected.

static
integral_contribution
(n)[source] Reference: http://dx.doi.org/10.1016/j.euromechflu.2016.11.015
 Parameters
n (int) – The number of DMD modes to be selected.
 Return callable
A function which can be used as the parameter of select_modes to select DMD modes according to the criteria of integral contribution.

static
stable_modes
(max_distance_from_unity=None, max_distance_from_unity_inside=None, max_distance_from_unity_outside=None)[source] Select all the modes corresponding to eigenvalues whose distance from the unit circle is less than or equal to a specified threshold. It is possible to specify the distance separately for eigenvalues inside and outside the unit circle, but you cannot set clashing thresholds.
The following are allowed combinations of parameters:
>>> # the maximum allowed distance from the unit circle (both ... # inside and outside) is 1.e3. >>> stable_modes(max_distance_from_unity=1.e3) >>> # the maximum allowed distance from the unit circle is 1.e3 ... # inside and 1.e4 outside. >>> stable_modes(max_distance_from_unity_inside=1.e3, ... max_distance_from_unity_outside=1.e4) >>> # the maximum allowed distance from the unit circle is 1.e4 ... # outside and unspecified (i.e. infinity) inside. >>> stable_modes(max_distance_from_unity_outside=1.e4)
Since max_distance_from_unity controls both inside and outside distance, you cannot set also max_distance_from_unity_inside or max_distance_from_unity_outside simultaneously:
>>> # this is not allowed >>> stable_modes(max_distance_from_unity=1.e3, ... max_distance_from_unity_inside=1.e4)
For code clarity reasons, the snippet above would have failed even if max_distance_from_unity_inside=1.e3.
 Parameters
max_distance_from_unity (float) – The maximum distance from the unit circle. Defaults to None.
max_distance_from_unity_inside (float) – The maximum distance from the unit circle for points inside it. Defaults to None.
max_distance_from_unity_outside (float) – The maximum distance from the unit circle for points outside it. Defaults to None.
 Return callable
A function which can be used as the parameter of select_modes to select DMD modes according to the criteria of stability.

static
threshold
(low_threshold, up_threshold)[source] Retain only DMD modes associated with an eigenvalue whose module is between low_threshold and up_threshold (inclusive on both sides).

static

class
ModesTuner
(dmds, in_place=False)[source] Bases:
object
Class for semiautomatic tuning of DMD modes.
This class generates a new instance from the instance passed to the constructor, and modifies that one whenever one of the tuning methods is called. Therefore there is no need to worry about subsequent unwanted changes in the given instance.
ModesTuner provides a simplified interface to the tuning functions
select_modes()
andstabilize_modes()
, but in order to have more control on what is happening (i.e. when to use inplace tuning, or to check which modes have been changed) you may prefer to use them instead. Parameters
dmds – One or more instances of DMD.
in_place (bool) – If True, this tuner works directly on the given DMD instance.

copy
()[source] Returns a deep copy of the private DMD instance(s) that ModesTuner is working on. They are not going to be modified by subsequent calls to tuning methods, and therefore provide a secure “snapshot” to the DMD(s).
 Returns
A copy of the private DMD instance owned by ModesTuner, or a list of copies depending on the parameter received by the constructor of this instance.
 Return type
list or pydmd.DMDBase

get
()[source] Returns the private DMD instance(s) that ModesTuner is working on. Be aware that those instances are the internal instances owned by ModesTuner, therefore they are going going to be modified by subsequent calls to tuning methods.
 Returns
The private DMD instance owned by ModesTuner, or a list of DMD instances depending on the parameter received by the constructor of this instance.
 Return type
list or pydmd.DMDBase

select
(criteria, nullify_amplitudes=False, **kwargs)[source] Select the DMD modes by using the given criteria, which can be either a string or a function. You can choose prepacked criteria by passing one of the allowed string values for criteria. In this case you need to pass (as keyword arguments) the arguments needed to construct the criteria (see example below).
Allowed string values for criteria:
‘module_threshold’: Retain modes such that the module of the corresponding eigenvalue is included in the interval [low_threshold, up_threshold] (cfr.
ModesSelectors.threshold()
);‘stable_modes’: Retain modes such that the corresponding eigenvalue is not far from the unit circle (cfr.
ModesSelectors.stable_modes()
);‘integral_contribution’: Retain the first n modes in terms of integral contribution (cfr.
ModesSelectors.integral_contribution()
).
You might want to read the documentation of
ModesSelectors
in order to get detailed info regarding the behavior of each argument.Example:
>>> from pydmd.dmd_modes_tuner import ModesTuner >>> mtuner = ModesTuner(dmd) >>> mtuner.select('stable_modes', max_distance_from_unity_inside=1.e1, max_distance_from_unity_outside=1.e3)
 Parameters
criteria (str or callable) – Criteria used to select DMD modes. The allowed strings are module_threshold, stable_modes and integral_contribution. If criteria is a function it must take an instance of DMD as the only parameter.
nullify_amplitudes (bool) – If True, the amplitudes associated with DMD modes to be removed are set to 0, therefore the number of DMD modes remains constant. If False (default) DMD modes are actually removed, therefore the number of DMD modes in the instance decreases.
**kwargs – Parameters passed to the chosen criteria (if criteria is a string).
 Return ModesTuner
This instance of ModesTuner in order to allow chaining multiple operations.

stabilize
(inner_radius, outer_radius=inf)[source] Stabilize modes in a circular sector of radius [inner_radius, outer_radius].
Stabilizing a mode means that the corresponding eigenvalue is divided by its module (i.e. normalized) in order to make the associated dynamic a trigonometric function with respect to the time (since the eigenvalue is projected on the unit circle). At the same time, the corresponding mode amplitude is multiplied by the former module of the eigenvalue, in order to “recover” the correctness of the result in the first time instants.
This approach may give better results in the prediction when one or more eigenvalues are strongly unstable (i.e. the corresponding DMD mode “explodes” several instants after the known time frame).
In order to stabilize an unbounded (above) circular sector, the parameter outer_radius should be set to np.inf (default).

subset
(indexes)[source] Generate a temporary instance of ModesTuner which operates on a subset of the DMD instances held by this ModesTuner.
 Parameters
indexes (list) – List of indexes of the DMD instances to be put into the subset.
 Return ModesTuner
A ModesTuner which operates “in place” on the DMD instances held by the caller ModesTuner.

select_modes
(dmd, criteria, in_place=True, return_indexes=False, nullify_amplitudes=False)[source] Select the DMD modes by using the given criteria. criteria is a function which takes as input the DMD object itself and return a numpy.ndarray of boolean where False indicates that the corresponding mode will be discarded. The class
ModesSelectors
contains some prepacked selector functions.Example:
>>> dmd = ... >>> def stable_modes(dmd): >>> toll = 1e3 >>> return np.abs(np.abs(dmd.eigs)  1) < toll >>> select_modes(dmd, stable_modes)
 Parameters
dmd (pydmd.DMDBase) – An instance of DMD from which we want to delete modes according to some criteria.
criteria (callable) – The function used to select the modes. Must return a boolean array (whose length is the number of DMD modes in dmd) such that True items correspond to retained DMD modes, while False items correspond to deleted modes.
in_place (bool) – If True, the given DMD instance will be modified according to the given criteria. Otherwise, a new instance will be created (via copy.deepcopy).
return_indexes (bool) – If True, this function returns the indexes corresponding to DMD modes cut using the given criteria (default False).
nullify_amplitudes (bool) – If True, the amplitudes associated with DMD modes to be removed are set to 0, therefore the number of DMD modes remains constant. If False (default) DMD modes are actually removed, therefore the number of DMD modes in the instance decreases.
 Returns
If return_indexes is True, the returned value is a tuple whose items are:
The modified DMD instance;
 The indexes (on the old DMD instance) corresponding to DMD modes
cut.
Otherwise, the returned value is the modified DMD instance.

stabilize_modes
(dmd, inner_radius, outer_radius=inf, in_place=True, return_indexes=False)[source] Stabilize modes in a circular sector of radius [inner_radius, outer_radius].
Stabilizing a mode means that the corresponding eigenvalue is divided by its module (i.e. normalized) in order to make the associated dynamic a trigonometric function with respect to the time (since the eigenvalue is projected on the unit circle). At the same time, the corresponding mode amplitude is multiplied by the former module of the eigenvalue, in order to “recover” the correctness of the result in the first time instants.
This approach may give better results in the prediction when one or more eigenvalues are strongly unstable (i.e. the corresponding DMD mode “explodes” several instants after the known time frame).
In order to stabilize an unbounded (above) circular sector, the parameter outer_radius should be set to np.inf (default).
 Parameters
dmd (pydmd.DMDBase) – An instance of DMD which we want to stabilize.
inner_radius (float) – The inner radius of the circular sector to be stabilized.
outer_radius (float) – The outer radius of the circular sector to be stabilized.
in_place (bool) – If True, the given DMD instance will be modified according to the given criteria. Otherwise, a new instance will be created (via copy.deepcopy).
return_indexes (bool) – If True, this function returns the indexes corresponding to DMD modes stabilized (default False).
 Returns
If return_indexes is True, the returned value is a tuple whose items are:
The modified DMD instance;
 The indexes (on the old DMD instance) corresponding to DMD modes
stabilized.
Otherwise, the returned value is the modified DMD instance.