DMD Modes Tuner

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

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:

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.

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

class ModesSelectors[source]

A container class which defines some static methods for pre-packed 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 “non-partialized”, 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 non-partialized selector. This mechanism is employed to reduce the boilerplate code needed while applying a selector.

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.e-3.
>>> stable_modes(max_distance_from_unity=1.e-3)
>>> # the maximum allowed distance from the unit circle is 1.e-3
... # inside and 1.e-4 outside.
>>> stable_modes(max_distance_from_unity_inside=1.e-3,
...   max_distance_from_unity_outside=1.e-4)
>>> # the maximum allowed distance from the unit circle is 1.e-4
... # outside and unspecified (i.e. infinity) inside.
>>> stable_modes(max_distance_from_unity_outside=1.e-4)

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.e-3,
...     max_distance_from_unity_inside=1.e-4)

For code clarity reasons, the snippet above would have failed even if max_distance_from_unity_inside=1.e-3.

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

Parameters
  • low_threshold (float) – The minimum accepted module of an eigenvalue.

  • up_threshold (float) – The maximum accepted module of an eigenvalue.

Return np.ndarray

An array of bool, where each “True” index means that the corresponding DMD mode is selected.

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

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:

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.

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 pre-packed selector functions.

Example:

>>> dmd = ...
>>> def stable_modes(dmd):
>>>    toll = 1e-3
>>>    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:

  1. The modified DMD instance;

  2. 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:

  1. The modified DMD instance;

  2. The indexes (on the old DMD instance) corresponding to DMD modes

    stabilized.

Otherwise, the returned value is the modified DMD instance.