DMD Modes Tuner

A module which contains several functions to tune (i.e. improve) DMD instances through the “manual” modification of DMD modes.

class ModesTuner(dmds, in_place=False)[source]

Bases: object

Class for semi-automatic 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() and stabilize_modes(), but in order to have more control on what is happening (i.e. when to use in-place 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 pre-packed 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.e-1,
        max_distance_from_unity_outside=1.e-3)
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).

Parameters:

  • 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.

Return ModesTuner:

This instance of ModesTuner in order to allow chaining multiple operations.

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.