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.