Gluing

orbithunter.gluing.tile(symbol_array, tiling_dictionary, orbit_type, **kwargs)[source]

Wraps the glue function so that configurations of symbols may be provided instead of configurations of Orbits.

Parameters
symbol_arraynumpy.ndarray

An array of dictionary keys which exist in tiling_dictionary

tiling_dictionarydict

A dictionary whose values are Orbit instances.

orbit_typetype

The type of Orbit that will be returned.

kwargs :

Orbit kwargs relevant to instantiation and gluing. See glue() for details.

Returns
Orbitorbit_type

An instance containing the glued state

orbithunter.gluing.glue(orbit_array, orbit_type, strip_wise=False, **kwargs)[source]

Combines the state arrays of a configuration of Orbits

Parameters
orbit_arrayndarray of Orbit instances

A NumPy array wherein each element is an orbit. i.e. a tensor of Orbit instances. The shape should be representative to how the orbits are going to be glued. See notes for more details. The orbits must all have the same discretization size if gluing is occuring along more than one axis. The orbits should all be in the physical field basis.

orbit_typeOrbit type

The class that the final result will be returned as.

strip_wisebool

If True, then the “strip-wise aspect ratio correction” is applied. See aspect_ratio_correction().

Returns
glued_orbitOrbit

Instance of type orbit_type, whose state and dimensions are the combination of the original array of orbits.

Notes

Because of how the concatenation of fields works, wherein the discretization must match along the boundaries. It is quite complicated to write a generalized code that glues all dimensions together at once for differently sized, orbit, so instead this is designed to iterate through the axes of the orbit_array.

To prevent confusion, there are many different notions of ‘shape’ and ‘discretization’ that are relevant. There are three main array shapes or dimensions that are involved in this function. The first is the array of orbits, which represents a spatiotemporal symbolic “dynamics” block. This array can have as many dimensions as the solutions to the equation have. An array of orbits of shape (2,1,1,1) means that the fields have four continuous dimensions. The specific shape means that two such fields are being concatenated in time (because the first axis should always be time) by orbithunter convention.

Example for the spatiotemporal Navier-stokes equation. The spacetime is (1+3) dimensional. Let’s assume we’re gluing two vector fields with the same discretization size, (N, X, Y, Z). We can think of this discretization as a collection of 3D vector field snapshots in time. Therefore, there are actually (N, X, Y, Z, 3) degrees of freedom. Therefore the actually tensor before the gluing will be of the shape (2, 1, 1, 1, N, X, Y, Z, 3). Because we are gluing the orbits along the time axis, The final shape will be (1, 1, 1, 1, 2*N, X, Y, Z, 3), given that the original X, Y, Z, are all the same size. Being forced to have everything the same size is what makes this difficult, because this dramatically complicates things for a multi-dimensional symbol array.

For a symbol array of shape (a, b, c, d) and orbit field with shape (N, X, Y, Z, 3) the final dimensions would be (a*N, b*X, c*Y, d*Z, 3). This is achieved by repeated concatenation along the axis corresponding to the last axis of the symbol array. i.e. for (a,b,c,d) this would be concatenation along axis=3, 4 times in a row. I believe that this generalizes for all equations but it has not been tested yet.

orbithunter.gluing.expensive_pairwise_glue(orbit_pair, objective='cost', axis=0, **kwargs)[source]

Gluing that searches pairs of group orbit members for the best combination.

Parameters
orbit_pairnp.ndarray

An array with the same number of dimensions as the orbits within them; i.e. (2, 1, 1, 1), (1, 2, 1, 1), … for Orbits with 4 dimensions.

orbit_typetype

The Orbit type to return the result as.

objectivestr

The manner that orbit combinations are graded; options are ‘cost’ or ‘boundary_cost’. The former calls the Orbit’s built in cost function, the latter computes the L2 difference of the boundaries that are joined together.

Returns
best_glued_orbit_so_farOrbit

The orbit combination in the pairwise group orbit that had the smallest objective function value.

Notes

Expensive gluing only supported for pairs of Orbits. For larger arrays of orbits, apply this function in an iterative manner if so desired.

This function can not only be expensive, it can be VERY expensive depending on the generator x.group_orbit(). It is highly advised to have some way of controlling how many members of each group orbit are being used. For example, for the K-S equation and its translational symmetries, the field arrays are typically being rolled; the option exists to roll by an integer “stride” value s.t. instead of shifting by one unit, a number of units equal to stride is shifted. Note that for group orbits of size 1000, this would construct and search over 1000000 combinations, unless a subset of the group orbit is specified.

orbithunter.gluing.generate_symbol_arrays(tiling_dictionary, glue_shape, unique=True)[source]

Produce all d-dimensional symbol arrays for a given dictionary and shape.

Parameters
tiling_dictionarydict

Dictionary whose keys are the orbit symbols and whose values are Orbits

glue_shapetuple

The shape of the gluing configuration (i.e. symbol array)

uniquebool

If True, then rotations of symbol arrays are treated as redundant.

Returns
list of ndarray :

A list of numpy arrays containing configurations of symbols (tiling_dictionary keys).

Notes

If unique = False then this produces a list of d^N elements, d being the dimension and N being the number of symbols in the dictionary. Clearly this can be a huge drain on resources in certain cases. If possible, it is better to take the group orbit of the glued orbits resulting from a symbol array than all possible symbol arrays.

orbithunter.gluing.rediscretize_tileset(tiling_dictionary, new_shape=None, **kwargs)[source]

Convenience tool for resizing all orbits in a tiling dictionary in a single function call

Parameters
tiling_dictionarydict

Keys are symbol alphabet, values are Orbits.

new_shapetuple, optional, default None

If provided as a shape tuple then all orbits in the tiling dictionary will be resized to this shape.

kwargsdict

Keyword arguments for Orbit.dimension_based_discretization() method

Returns
dict :

Tiling dictionary whose values (Orbits) have been resized.

orbithunter.gluing.aspect_ratio_correction(orbit_array, axis=0, conserve_parity=True)[source]

Resize a collection of Orbits’ discretizations according to their sizes in the dimension specified by axis.

Parameters
orbit_arrayndarray

An array of orbits to resize along ‘axis’

axisint

ndarray axis along which to resize with respect to.

conserve_paritybool

Whether or not to maintain parity of the discretization size for each orbit. This is relevant when certain bases require either odd or even numbered discretization sizes.

Returns
ndarray :

An array of resized orbits, same shape as orbit_array.

Notes

Note that this will allow equilibria tiles to become very distorted; this can be managed by gluing order but typically when including equilibria, strip-wise corrections cause too much distortion to be useful. This is not an issue, however, as this method should never really be used for dramatically different sized Orbits unless the distortions are permitted.