Developer Guide

Preface

The following guide demonstrates the class methods required for full functionality in the orbithunter framework. This documentatino is presented much like how one might document their own equation module for inclusion in the main orbithunter branch. The creator of orbithunter Matthew Gudorf developed the framework to be as agnostic of equation as possible. That is, the techniques and tools should generalize to any equation, so long as the proper class methods are written. Because of this, the following is presented as a template for each technique or submodule. Implementation of the methods in each section should enable the functionality of the corresponding orbithunter module.

Orbithunter was designed with field equations in mind; that is, where the Orbit state array is a continuous function with respect to its dimensions. While it has not been tested, the package should work all the same as long as the user treats the vector components as a “discrete dimension”, i.e. arrays of shape (#, #, #, #, 3) or something similar.

Warning

Be sure to check the base orbithunter.core.Orbit class before writing your methods; there very well may be methods which already exist but are not included here either for brevity and because they generalize to other equations.

SymmetryOrbitEQN Class

As mentioned in the preface, orbithunter has tried to do most of the heavy lifting. For the user, the task of implementing a module for a new equation is as simple as implementing a certain subset of methods that are equation and or dimension dependent. If the following list of methods is completed, then all orbithunter utilities should be available. The lion’s share is implementing the spatiotemporal equations and its gradients. The main successes have been made using spectral methods, which leverage expansions in terms of global, spatiotemporal basis functions. It is believed that there is an intimate link between these expansions and keeping the spatiotemporal domain sizes variable quantities, and so only usage of spectral methods is recommended. For periodic boundary conditions we recommended using a Fourier basis and for aperiodic boundary conditions Chebyshev polynomial bases are recommended.

Note

This is also available as a .py file in the tutorials under class_template

class template.class_template.SymmetryOrbitEQN(state=None, basis=None, parameters=None, discretization=None, constraints=None, **kwargs)[source]

Template for implementing other equations. Name is demonstration of orbithunter naming conventions

Parameters
statendarray, default None

If an array, it should contain the state values congruent with the ‘basis’ argument.

basisstr, default None

Which basis the array state is currently in.

parameterstuple, default None

Parameters required to uniquely define the Orbit.

discretizationtuple, default None

The shape of the state array in configuration space, i.e. the ‘physical’ basis.

constraintsdict, default None

Dictionary whose labels are parameter labels, and values are bool. If True, then corresponding parameter will be treated as a constant during optimization routines.

kwargs :

Possible extra arguments for _parse_parameters and _parse_state.

Notes

The name of the base class for new equations should be Orbit + equation acronym, symmetry subclasses adding a prefix which describes said symmetry.

Methods

Static Methods

Methods decorated with @staticmethod

SymmetryOrbitEQN.bases_labels

Labels of the different bases that ‘state’ attribute can be in.

SymmetryOrbitEQN.parameter_labels

Strings to use to label dimensions.

SymmetryOrbitEQN.discretization_labels

Strings to use to label discretization variables.

SymmetryOrbitEQN.dimension_labels

Strings to use to label dimensions/periods; typically a subset of parameter_labels.

SymmetryOrbitEQN.minimal_shape

The smallest possible discretization that can be used without methods breaking down.

SymmetryOrbitEQN.minimal_shape_increments

The smallest valid increment to change the discretization by.

SymmetryOrbitEQN.continuous_dimensions

Bools indicating whether an array’s axes represent continuous dimensions or not.

Governing Equations

Implementation of the governing equations is the lion’s share of the work and the most important part; matvec and rmatvec return the product of Jacobian and Jacobian transpose with a matrix; preferably without construction of the matrix itself. For certain numerical methods to work, these methods must handle parameters in a special way. See each individual method for details.

SymmetryOrbitEQN.eqn

Return an instance whose state is an evaluation of the governing equations.

SymmetryOrbitEQN.matvec

Matrix-vector product of self.jacobian and other.orbit_vector

SymmetryOrbitEQN.rmatvec

Matrix-vector product of adjoint of self.jacobian and other.state

SymmetryOrbitEQN.jacobian

Jacobian matrix evaluated at the current state.

Numerical Optimization

SymmetryOrbitEQN.cost([evaleqn])

Cost function evaluated at current state.

SymmetryOrbitEQN.costgrad(eqn, **kwargs)

Gradient of cost function; optional unless cost was defined

Second Order Numerical Optimization

Certain algorithms require the Hessian matrix of the matrix vector product thereof. The SciPy implementations of the numerical methods that use these are fully developed but the orbithunter API still requires testing. Likewise, there are issues that are on SciPy’s end with using finite difference methods. They’ve been reported to their github issues page, see github issues for details.

SymmetryOrbitEQN.hessp(left_other, …)

Tensor product u * H * v where H is the matrix of second derivatives of governing equations.

SymmetryOrbitEQN.hess(**kwargs)

Matrix of second derivatives of the governing equations.

SymmetryOrbitEQN.costhess(other, **kwargs)

Hessian matrix of the cost function

SymmetryOrbitEQN.costhessp(other, **kwargs)

Matrix-vector product with the Hessian of the cost function

Defaults

SymmetryOrbitEQN._default_shape()

The default array shape when dimensions are not specified.

SymmetryOrbitEQN._default_parameter_ranges()

Intervals (continuous) or iterables (discrete) used to populate parameters.

SymmetryOrbitEQN._default_constraints()

Sometimes parameters are necessary but constant; this allows for exclusion from optimization without hassle.

SymmetryOrbitEQN._dimension_indexing_order()

Indicates whether numpy indexing corresponds to increasing or decreasing values configuration space variable

State Transformations

These methods are recommended but optional methods; the base orbit class has simple implementations for all of these

SymmetryOrbitEQN.glue_dimensions(…[, …])

Strategy for combining tile dimensions in gluing; default is arithmetic averaging.

SymmetryOrbitEQN._pad(size[, axis])

Increase the size of the discretization along an axis.

SymmetryOrbitEQN._truncate(size[, axis])

Decrease the size of the discretization along an axis

Other

The methods in this section are ones which really cannot be generalized at all, methods which may be heavily reliant on equation and methods which do not really fit anywhere else on this list. .

SymmetryOrbitEQN.plot([show, save, padding, …])

Signature for plotting method.

SymmetryOrbitEQN.from_numpy_array(cdof, …)

Utility to convert from numpy array (orbit_vector) to Orbit instance for scipy wrappers.

SymmetryOrbitEQN.dimension_based_discretization(…)

Follow orbithunter conventions for discretization size.

SymmetryOrbitEQN.periodic_dimensions()

Bools indicating whether or not dimension is periodic for persistent homology calculations.