OrbitKS

Overview

class orbithunter.OrbitKS(state=None, basis=None, parameters=None, discretization=None, constraints=None, **kwargs)

Base class for orbits of the Kuramoto-Sivashinsky equation.

The Kuramoto-Sivashinsky equation is a fourth order partial differential equation that serves as a simplified testing ground for the more complicated Navier-Stokes equation. It’s form in configuration space, where the state variable \(u(t,x)\) is typically imagined as a velocity field of a laminar flame front. It’s spatiotemporal version with doubly periodic boundary conditions takes the form

\(u_t + u_{xx} + u_{xxxx} + 1/2(u^2)_x = 0\)

with boundary conditions

\(u(t, x) = u(t + T, x) = u(t, x+L) = u(t+T, x+L)\).

This class and its subclasses is used to find solutions to the system of differential algebraic equations (DAEs) which result from applying a discrete Fourier transform in both space and time.

The ‘state’ in configuration space is ordered such that when in the physical basis, the last row corresponds to ‘t=0’. This results in an extra negative sign when computing time derivatives. This convention was chosen because it is conventional to display positive time as ‘up’. This convention prevents errors due to flipping fields up and down.

To define an orbit, the configuration space (spatiotemporal dimensions) or tile must be defined. The unconventional approach of this package is to keep these domain dimensions as free variables.

The only additional parameter beyond the dimensions is a spatial shift parameter for solutions with continuous spatial translation symmetry; it only applies to orbithunter.ks.orbits.RelativeOrbitKS and orbithunter.ks.orbits.RelativeEquilibriumOrbitKS. Its inclusion in the class orbithunter.ks.orbits.OrbitKS is due to the ability to convert between Orbit types. The various subclasses represent symmetry invariant subspaces. Due to the nature of subspaces, it is numerically possible to find, for example, solutions with spatial reflection symmetry using OrbitKS. The discrete symmetry invariant orbits are literaly subspaces of solutions; any subclass member can be found using its parent class.

Historically, only adj and lstsq were used, in combination, for OrbitKS and its subclasses: All possible methods include:

• ‘adj’

• ‘newton_descent’

• ‘lstsq’

• ‘lsqr’

• ‘lsmr’

• ‘bicg’

• ‘bicgstab’

• ‘gmres’

• ‘lgmres’

• ‘cg’

• ‘cgs’

• ‘qmr’

• ‘minres’

• ‘gcrotmk’

• ‘cg_min’

• ‘bfgs’

• ‘newton-cg’

• ‘l-bfgs-b’

• ‘tns’

• ‘slsqp’

Warning

If dimensions change by dramatic/nonsensible amounts then preconditioning=True can be used with certain methods (most notably, ‘adj’) to account for very large parameter gradients.

Warning

The following are supported but NOT recommended for the KSE.

• ‘nelder-mead’ (very very slow)

• ‘powell’ (very slow)

• ‘cobyla’ (slow),

See also

orbithunter.core.Orbit

Methods

Initialization

OrbitKS.__init__([state, basis, parameters, …])	Initialize self.
OrbitKS.populate([attr])	Initialize random parameters or state or both.
OrbitKS._populate_state(**kwargs)	Initialize a set of random spatiotemporal Fourier modes
OrbitKS._populate_parameters(**kwargs)	Should only be accessed through Orbit.populate()

Special Methods

“Special” methods also known as “magic” or “dunder” (double underscore) methods account for most basic Math operations and other operations pertaining to NumPy arrays.

Note

See Orbit for more details.

Properties

OrbitKS.shape	Current state array’s shape
OrbitKS.size	Current state array’s dimensionality
OrbitKS.ndim	Current state array’s number of dimensions

Discretization and Dimensions

OrbitKS.shapes()	State array shapes in different bases; determined by symmetry selection rules.
OrbitKS.dimensions()	Tile dimensions.
OrbitKS.glue_dimensions(dimension_tuples, …)	Strategy for combining tile dimensions in gluing; default is arithmetic averaging.
OrbitKS.dimension_based_discretization(…)	Return discretization size according to orbithunter conventions for the KSe.
OrbitKS.plotting_dimensions()	Dimensions according to plot labels; used in clipping.

Math Functions

OrbitKS.orbit_vector()	Vector representation of Orbit instance; constants all variables required to define the Orbit instance.
OrbitKS.abs()	Orbit instance with absolute value of state.
OrbitKS.dot(other)	Return the L_2 inner product of two orbits
OrbitKS.norm([order])	Norm of spatiotemporal state via numpy.linalg.norm
OrbitKS.dx(**kwargs)	Spatial derivative of the current state.
OrbitKS.dt([order, array])	Spectral time derivatives of the current state.
OrbitKS.eqn(**kwargs)	Instance whose state is the Kuramoto-Sivashinsky equation evaluated at the current state
OrbitKS.matvec(other, **kwargs)	Matrix-vector product of a vector with the Jacobian of the current state.
OrbitKS.rmatvec(other, **kwargs)	Matrix-vector product with the adjoint of the Jacobian
OrbitKS.precondition(**kwargs)	Rescale a vector with the inverse (absolute value) of linear spatial terms
OrbitKS.jacobian(**kwargs)	Jacobian matrix evaluated at the current state.

Visualization

OrbitKS.plot([show, save, padding, …])	Plot the velocity field as a 2-d density plot using matplotlib’s imshow
OrbitKS.mode_plot([show, save, scale])	Plot the spatiotemporal Fourier spectrum as a 2-d density plot using matplotlib’s imshow

State Transformations

OrbitKS.transform([to, array, inplace])	Transform current state to a different basis.
OrbitKS.resize(*new_discretization, **kwargs)	Rediscretize the current state typically via zero padding or interpolation.
OrbitKS.reflection([axis, signed])	Reflect the velocity field about the spatial midpoint
OrbitKS.roll(shift[, axis])	Apply numpy roll along specified axis.
OrbitKS.cell_shift(n_cell[, axis])	Rotate by fraction of the period in either axis; nearest discrete approximate is taken.
OrbitKS.rotate(distance[, axis, units])	Rotate the velocity field in either space or time.
OrbitKS.shift_reflection()	Return a OrbitKS with shift-reflected velocity field
OrbitKS.to_fundamental_domain(**kwargs)	Placeholder/signature for possible symmetry subclasses.
OrbitKS.from_fundamental_domain(**kwargs)	Placeholder/signature for possible symmetry subclasses.
OrbitKS._pad(size[, axis])	Increase the size of the discretization via zero-padding
OrbitKS._truncate(size[, axis])	Decrease the size of the discretization via truncation

Static

OrbitKS.bases_labels()	Labels of the different bases produced by transforms.
OrbitKS.minimal_shape()	The smallest possible compatible discretization to have full functionality.
OrbitKS.minimal_shape_increments()	The smallest valid increment to change the discretization by.
OrbitKS.discretization_labels()	Strings to use to label dimensions/periods
OrbitKS.parameter_labels()	Labels of all parameters
OrbitKS.dimension_labels()	Strings to use to label dimensions/periods.
OrbitKS.periodic_dimensions()	Bools indicating whether or not dimension is periodic.
OrbitKS.positive_indexing()	Indicates whether numpy indexing corresponds to increasing or decreasing values configuration space variable

Other

OrbitKS.copy()	Return an instance with copies of copy-able attributes.
OrbitKS.mask(masking_array[, invert])	Return an Orbit instance with a numpy masked array state
OrbitKS.constrain(*labels)	Set self constraints based on labels provided.
OrbitKS.preprocess()	Check whether the orbit converged to an equilibrium or close-to-zero solution

Defaults

OrbitKS.defaults()	Dict of default values for constraints, parameter ranges, sizes, etc.
OrbitKS._default_shape()	The default array shape when dimensions are not specified.
OrbitKS._default_parameter_ranges()	Default parameter ranges.
OrbitKS._default_constraints()	Defaults for whether or not parameters are constrained.

Reading and Writing Data

OrbitKS.filename([extension, decimals, cls_name])	Method for convenience and consistent/conventional file naming.
OrbitKS.to_h5([filename, dataname, h5mode, …])	Export current state information to HDF5 file.