zapata.koopman module¶

Koopman Analysis¶

Routines and methods for Koopman analysis

This module contains the tools for performing a Koopman or Perron decomposition on time series of vector data. It is based on Klus routines in module Klus.

Classes¶

Koop Transfer Operator

KoopGen Generator Transfer Operator

Examples

>>> options = {'operator': 'Koopman',
>>>            'kernel_choice': 'poly', 'k_shift':0.1,
>>>           'poly_shift':0,'poly_order':1,
>>>           'bandwidth': 'std',
>>>           'epsilon':1e-5,'time_data': X.A.time.data[:-1]}
>>> KK=zkop.Koop(vdat,**options)
>>> KK.fit(bandwidth='std')

zapata.koopman.choose_eig(option, ww, tol, dt)[source]¶

Choose stable eigenvalues, either according their absolute value or according the sign of the real part

Parameters:

ww (complex) -- Koopman Eigenvalues
option --
- one Eigenvalues close to one in Abs less than tol
- stable Real part < 0
- unstable Real part > 0
tol -- Tolerance
dt -- Time interval used for the Koopman eigenvalues calculation

Returns:

Index of selected eigenvalues

Return type:

ind

zapata.koopman.reconstruct_koopman(w, phi0, v, dt, n, decode=None)[source]¶

Linear decomposition with Koopman modes

Parameters:

w -- Koopman Generator Eigenvalues
phi0 -- Initial values for the eigenfunctions
v -- Koopman modes
dt -- Timesteps
n -- Number of time steps
decode -- If not empty contains the array for decoding to physical space

Returns:

Predicted values

Return type:

x

zapata.koopman.check_sim(ax, X, tit, option='std')[source]¶

Compute scale for kernel

Parameters:

ax -- Axes for histogram plot
X -- Data Matrix
tit -- Title for histogram
option -- Type of scale * 'std' Standard deviation * 'median' Median

Returns:

scale -- Scale required for the bandwidth

Return type:

float

zapata.koopman.order_w(w, option='magnitude', direction='up', tdelta=1)[source]¶

Order Eigenvalues according to option

Parameters:

option (String) --
- 'magnitude' abs(w)
- 'frequency' w.imag
- 'growth' log(w).real/dt
- 'ones' abs(w) closest to 1.0
- 'stable' log(w).real/dt irrespextive of sign
direction (String) --
- 'up' descending
- 'down' ascending
delta -- Sampling frequency

Returns:

w0 (Array) -- Ordered Koopman Eigenvalues
w1 (Array) -- Ordered generator eigenvalues
ind (Array) -- Index of order for ordering Koopman modes

zapata.koopman.expand_modes(v_o, KM_o, VM_o, vw_o, v_s, KM_s, VM_s, vw_s, modetype='', description='', X=None, file=None)[source]¶

Expand modes into the original data shape, optionally write to disk. complex numbers are not supported by netcdf4, so we use h5netcdf with ds.to_netcdf(file,engine="h5netcdf", invalid_netcdf=True)

Parameters:

v_o,KM_o,VM_o, vw_o (Arrays) -- Original norms, Koopman Modes, Eigenfunction values, Eigenvalues
v_s,KM_s,VM_s,vw_s (Arrays) -- Ordered, norms, Koopman Modes, Eigenfunction values, Eigenvalues
X (Xmat class) -- Original data array with geographical information.
file (str) -- Name of file to be written. Optional, if None no file is written

Returns:

ds -- Dataset with Koopman decomposition

Return type:

Xarray Dataset

Examples

>>> dskm = zkop.expand_modes(v_o,KM_o,VM_o, vw_o,v_s,KM_s,VM_s,vw_s , X=X,file='filename')
>>> # Read with
>>> dds=xr.open_dataset('filename',engine='h5netcdf')

zapata.koopman.find_modes(tper, wto, vrange, **kwargs)[source]¶

Find modes close to a specific Period tper within a specified vrange in month

Parameters:

tper -- Target Period (in years)
wto -- Koopman Generator Eigenvalues Also accept all other arguments for isclose
vrange -- Range (months)

Returns:

Index into closest period to tper

Return type:

ind

zapata.koopman.density_estimate(data, interval=[-1, -1, 400], kernel='gaussian', bw=0.05, **kwargs)[source]¶

Compute density estimation Using kde from sklearn

Parameters:

data (1D array) -- Array 1D of data to be analyzed
interval (list) -- [min,max, number_of_points]
kernel -- kernel for estimation (default gaussian)
bw -- Bandwidth for the kernel
Other arguments to `kde` can be passed on

Returns:

X (Array) -- Points where the distribution is computed
points (Array) -- Value of the distribution
kde (Object) -- The Density object

Examples

>>> density_estimate(data,interval=[-1,-1,400],kernel='gaussian',bw=0.05)

zapata.koopman.one_over(y)[source]¶: Vectorized 1/x, treating x==0 manually

zapata.koopman.one_over_years(y)[source]¶: Vectorized 1/x, treating x==0 manually Period calculation from imaginary part of generator eigenvalues 2 pi/log(w.imag)

class zapata.koopman.Koop(vdat, **kwargs)[source]¶

Bases: object

This class creates the Koopman operator

The input array is supposed to be in features/samples form The augemnted matrix is created inside

Parameters:

vdat (array) -- Data array with features and samples
**kwargs (dict) --
- 'operator' Choice of operator Koopman or Perron
- 'deltat' Time interval between samples
- 'kernel_choice' Kernel choice , gauss,`poly`
- 'sigma' Bandwidth for Gaussian kernel
  - 'std' -- Standard Deviation of distances
  - 'median -- Median of distances
  - '100' -- Explicit value
- 'epsilon' Regularization parameter
- 'maxeig' Max number of eigenvalues to compute
- 'poly_order': 1 Order of polynomial kernel
- 'poly_shift':0 Shift of polynomial kernel

Variables:

PsiX (numpy array) -- Reduced data matrix of type array
PsiY (numpy array) -- Shifted data matrix of type array
ntime (int) -- Number of samples or time points
npoints (int) -- Number of features or spatial points
deltat (float) -- Time interval between samples
operator (str) -- Operator chosen {'Koopman', 'Perron'}
kernel_choice (object) -- Kernel used in the estimator
epsilon (float) -- Tikhonov Regularization parameter {1e-5}
sigma (float) -- Bandwidth for Gaussian kernel
maxeig (int) -- Maximum number of eigenvalues to compute
poly_order (int) -- Order polynomial kernel
poly_shift (float) -- Shift polynomial kernel
ww (array) -- Koopman eigenvalues
wwg (array) -- Koopman generator eigenvalues
cc (array) -- Koopman eigenfunctions coefficients
vv (array) -- Koopman eigenfunction values on the samples
wf (array) -- Filtered Koopman eigenvalues
wfg (array) -- Filtered Koopman generator eigenvalues
vvf (array) -- Filtered Koopman eigenfunction values on the samples
Gxx (array) -- Kernel Matrix Gxx
Gxy (array) -- Kernel Matrix Gxy
ker (object) -- Object Kernel used
time_data -- Time array (optional)

Examples

Create a Koopman operator

>>> K = Koop(X, {operator: 'koopman',
        kernel_choice : 'gauss', sigma : 42, epsilon : 1e-5})

PsiX¶: Reduced Data matrix of type (array)

PsiY¶: Shifted data matrix of type (array)

ntime¶: Number of samples or time points (int)

npoints¶: Number of features or spatial points (int)

deltat¶: Time interval between samples (float)

bandwidth¶: Option Bandwidth for Gaussian kernel (str)

sigma¶: Bandwidth for Gaussian kernel (float)

operator¶: Operator chosen (str) {'Koopman', 'Perron'}

kernel_choice¶: Kernel used in the estimator (str)

epsilon¶: Tikhonov Regularization parameter (float) {1e-5}

maxeig¶: Maximum number of eigenvalues to compute (int)

poly_order¶: Order polynomial kernel (int)

poly_shift¶: Shift polynomial kernel (float)

k_shift¶: Shift kernel (float)

time_data¶

wf¶: Filtered Koopman eigenvalues (array)

wfg¶: Filtered Koopman generator eigenvalues (array)

vvf¶: Filtered Koopman eigenfunction values on the samples (array)

ww¶: Koopman eigenvalues (array)

wwg¶: Koopman generator eigenvalues (array)

vv¶: Koopman eigenfunction values on the samples (array)

cc¶: Koopman eigenfunctions coefficients (array)

Gxx¶: Kernel Matrix Gxx (array)

Gxy¶: Kernel Matrix Gxy (array)

ker¶: Kernel used (object)

fit(bandwidth=None, verbose=False)[source]¶

Fitting estimator. Select bandwidth with bandwidth

Parameters:

bandwidth (string) --
Select the bandiwidth for the Gaussian kernel
- 'std' Use bandwidth that make the distances of std 1
- 'median' Use median value of distances
- '100' Use this explicit numerical value
verbose (Boolean) -- True Print Messages False No Messages (Defaults)

Returns:

ww -- Eigenvalues
self.wwg = np.log(ww_tot)/self.deltat -- Generator Eigenvalues
self.vv -- Value of Eigenfunctions at samples
self.Gxx -- kernel matrix Gxx
self.Gxy -- kernel matrix Gxy
self.ker -- Kernel used

order(choice='frequency', direction='down', cut_period=3)[source]¶

Order Eigenvalues according to option

Parameters:

option --
- 'magnitude' abs(w)
- 'frequency' w.imag
- 'growth' log(w).real/dt
- 'ones' abs(w) closest to 1.0
- 'stable' log(w).real/dt irrespextive of sign
direction --
- 'up' descending
- 'down' ascending
cut_period -- Eliminate modes with shorter periods (sample units)

Returns:

wf -- Ordered Koopman Eigenvalues
wfg -- Ordered generator eigenvalues
vvf -- Ordered Koopman eigenfunctions

eigone(ww, vv, tol=0.1, select='one', verbose=True)[source]¶

Choose stable eigenvalues, either according their absolute value or according the sign of the real part

Parameters:

ww (complex) -- Koopman Eigenvalues
vv (array complex) -- Koopman eigenfunctions
select --
- one Eigenvalues close to one in Abs less than tol
- stable Real part < 0
- unstable Real part > 0
tol -- Tolerance
verbose -- Print Diagnostics

Returns:

ww -- Selected eigenvalues
vv -- Selected eigenfunctions
ind -- Index of selected eigenvalues

compute_modes(ww, vv, modetype='', description='', normalization=False)[source]¶

Compute Koopman Modes

Parameters:

ww -- Koopman eigenvalues
vv -- Value of Koopman EIgenfunctions at samples
modetype -- Descriptive label
description -- Data Descritpion
normalization -- If False (Default) the eigenfunctions are not normalized, se to`True` to get Koopman modes over normalized eigenfunctions.

Returns:

ds --

Content for ds¶
Variable	Description
keig(time,modes)	Normalized Koopman eignfunction values at sample points
kmodes(features,modes)	Koopman modes
periods	Periods of Koopman modes
eigenvalues	Koopman Eigenvalues

Return type:

data set

reconstruct_koopman(ds, decode=None, select_modes=None)[source]¶

Reconstruction of data from Koopman modes

Parameters:

ds -- Koopman decomposition from compute_modes
decode -- Array decoding features
decode -- If not empty contains the array for decoding to physical space
select_modes (list) -- If not empty reconstrut using only selected modes [2,7,4]

Returns:

data -- Reconstructed data

Return type:

Array

find_norm_modes(KM, KE, KEI, sort='sort', decode=None, simplify_conjugates=True)[source]¶

Compute norms of eigenfunctions eliminate complex conjugates, optionally sort in order of magnitude

Parameters:

KM -- Koopman Modes (KM)
KE -- Koopman Eigenfunctions (KE)
KEI -- Koopman EIgenvalues (KEI)
sort -- 'sort' -- get also sorted eigenvector in order of magnitude
decode -- None -- No decoding is applied, otherwise use array decode
simplify_conjugates -- If True only modes with imaginary part >= 0 are retained

Returns:

(vnorm, KM, VM, KEI) -- Koopman Modes Norms, Koopman Modes, Eigenfunctions, Eigenvalues
(vnormsort, KM_sort, VM_sort, KEI_sort) -- Sorted Koopman Modes Norms, Koopman Modes, Eigenfunctions, Eigenvalues

eigenfunction_value(x, mode)[source]¶

Compute eigenfunction value at point x

Parameters:

x -- Point at which eigenfunction is computed
mode -- Eigenfunction number

Return type:

eigenfunction value

class zapata.koopman.KoopGen(vdat, **kwargs)[source]¶

Bases: object

This class creates the Generator Koopman operator

The input array is supposed to be in features/samples form The augemnted matrix is created inside

Parameters:

vdat (array) -- Data array with features and samples
**kwargs (dict) --
- 'operator' Choice of operator Koopman or Perron
- 'deltat' Time interval between samples
- 'kernel_choice' Kernel choice , gauss,`poly`
- 'sigma' Bandwidth for Gaussian kernel
  - 'std' -- Standard Deviation of distances
  - 'median -- Median of distances
  - '100' -- Explicit value
- 'epsilon' Regularization parameter
- 'maxeig' Max number of eigenvalues to compute
- 'poly_order': 1 Order of polynomial kernel
- 'poly_shift':0 Shift of polynomial kernel

Variables:

PsiX (numpy array) -- Reduced data matrix of type array
PsiY (numpy array) -- Shifted data matrix of type array
ntime (int) -- Number of samples or time points
npoints (int) -- Number of features or spatial points
deltat (float) -- Time interval between samples
operator (str) -- Operator chosen {'Koopman', 'Perron'}
kernel_choice (object) -- Kernel used in the estimator
epsilon (float) -- Tikhonov Regularization parameter {1e-5}
sigma (float) -- Bandwidth for Gaussian kernel
maxeig (int) -- Maximum number of eigenvalues to compute
poly_order (int) -- Order polynomial kernel
poly_shift (float) -- Shift polynomial kernel
ww (array) -- Koopman eigenvalues
wwg (array) -- Koopman generator eigenvalues
vv (array) -- Koopman eigenfunction values on the samples
wf (array) -- Filtered Koopman eigenvalues
wfg (array) -- Filtered Koopman generator eigenvalues
vvf (array) -- Filtered Koopman eigenfunction values on the samples
Gxx (array) -- Kernel Matrix Gxx
Gxy (array) -- Kernel Matrix Gxy
ker (object) -- Object Kernel used

Examples

Create a Koopman operator

>>> K = Koop(X, {operator: 'koopman',
        kernel_choice : 'gauss', sigma : 42, epsilon : 1e-5})

PsiX¶: Reduced Data matrix of type (array)

PsiY¶: Shifted data matrix of type (array)

ntime¶: Number of samples or time points (int)

npoints¶: Number of features or spatial points (int)

deltat¶: Time interval between samples (float)

bandwidth¶: Option Bandwidth for Gaussian kernel (str)

sigma¶: Bandwidth for Gaussian kernel (float)

operator¶: Operator chosen (str) {'Koopman', 'Perron'}

kernel_choice¶: Kernel used in the estimator (str)

epsilon¶: Tikhonov Regularization parameter (float) {1e-5}

maxeig¶: Maximum number of eigenvalues to compute (int)

poly_order¶: Order polynomial kernel (int)

poly_shift¶: Shift polynomial kernel (float)

k_shift¶: Shift kernel (float)

wf¶: Filtered Koopman eigenvalues (array)

wfg¶: Filtered Koopman generator eigenvalues (array)

vvf¶: Filtered Koopman eigenfunction values on the samples (array)

ww¶: Koopman eigenvalues (array)

wwg¶: Koopman generator eigenvalues (array)

vv¶: Koopman eigenfunction values on the samples (array)

Gxx¶: Kernel Matrix Gxx (array)

Gxy¶: Kernel Matrix Gxy (array)

ker¶: Kernel used (object)

fit(bandwidth=None, derivative=None)[source]¶

Fitting generator estimator. Select bandwidth with bandwidth

Parameters:

bandwidth (string) --
Select the bandiwidth for the Gaussian kernel
- 'std' Use bandwidth that make the distances of std 1
- 'median' Use median value of distances
- '100' Use this explicit numerical value
derivative (array) -- Derivative of the data to be used in the generator. If not provided, the derivative is computed. (not implemented)

Returns:

ww -- Eigenvalues
self.wwg = np.log(ww_tot)/self.deltat -- Generator Eigenvalues
self.vv -- Value of Eigenfunctions at samples
self.Gxx -- kernel matrix Gxx
self.Gxy -- kernel matrix Gxy
self.ker -- Kernel used

order(choice='frequency', direction='down', cut_period=3)[source]¶

Order Eigenvalues according to option

Parameters:

option --
- 'magnitude' abs(w)
- 'frequency' w.imag
- 'growth' log(w).real/dt
- 'ones' abs(w) closest to 1.0
- 'stable' log(w).real/dt irrespextive of sign
direction --
- 'up' descending
- 'down' ascending
cut_period -- Eliminate modes with shorter periods (sample units)

Returns:

wf -- Ordered Koopman Eigenvalues
wfg -- Ordered generator eigenvalues
vvf -- Ordered Koopman eigenfunctions

eigzero(ww, vv, tol=0.1, option='zero')[source]¶

Choose stable eigenvalues, either according their absolute value or according the sign of the real part

Parameters:

ww (complex) -- Koopman Generator Eigenvalues
vv (array complex) -- Koopman eigenfunctions
select --
- zero Eigenvalues close to zero real part less than tol
- stable Real part < 0
- unstable Real part > 0
tol -- Tolerance

Returns:

ww -- Selected eigenvalues
vv -- Selected eigenfunctions
ind -- Index of selected eigenvalues

compute_modes(ww, vv, modetype='', description='')[source]¶

Compute Koopman Modes

Parameters:

ww -- Koopman eigenvalues
vv -- Value of Koopman EIgenfunctions at samples
modetype -- Descriptive label
description -- Data Descritpion

Returns:

ds --

Content for ds¶
Variable	Description
keig(time,modes)	Koopman eignfunction values at sample points
kmodes(features,modes)	Koopman modes
periods	Periods of Koopman modes
eigenvalues	Koopman Eigenvalues

Return type:

data set

reconstruct_koopman(ds, decode=None, select_modes=None)[source]¶

Reconstruction of data from Koopman modes

Parameters:

ds -- data set from compute_modes
decode -- Array decoding features
decode -- If not empty contains the array for decoding to physical space
select_modes (list) -- If not empty reconstrut using only selected modes [2,7,4]

Returns:

data -- Reconstructed data

Return type:

Array

find_norm_modes(KM, KE, KEI, sort='sort', decode=None)[source]¶

Compute norms of eigenfunctions eliminate complex conjugates, optionally sort in order of magnitude

Parameters:

KM -- Koopman Modes (KM)
KE -- Koopman Eigenfunctions (KE)
KEI -- Koopman EIgenvalues (KEI)
sort -- 'sort' -- get also sorted eigenvector in order of magnitude
decode -- None -- No decoding is applied, otherwise use array decode

Returns:

(vnorm, KM, VM, KEI) -- Norms, Koopman Modes, Eigenfunctions, Eigenvalues
(vnormsort, KM_sort, VM_sort, KEI_sort) -- Sorted Norms, Koopman Modes, Eigenfunctions, Eigenvalues

class zapata.koopman.KEig(k, X, v, nv)[source]¶

Bases: object

Class for computing eigenfunctions values from coefficients

k¶: Kernel

X¶: Data matrix containing snapshots

v¶: Coefficients of eigenfunction

nv¶: Order of the Eigenfunction

n¶: Dimension of state space

m¶: Number of snapshots

max¶: Max of eigenfunction values

min¶: Min of eigenfunction values

d¶: Distance of eigenfunction

fdfeval(x)[source]¶: Function and gradient evaluation.

xmax(fac)[source]¶

Extract States within a certain factor from Max

Inputs:: fac Distance from Max
Return:: test the average state indv the indices of the states averaged

xmin(fac)[source]¶

Extract States within a certain factor from Min

Inputs:: fac Distance from Max
Return:: test the average state indv the indices of the states averaged

xclose(val, tol=0.001)[source]¶

Extract States close a certain factor from max

Return:: test the average state indv the indices of the states averaged

zapata.koopman module¶

Koopman Analysis¶

Classes¶

Table of Contents

Previous topic

Next topic

This Page