Basins functions

BasinsOfAttraction

A subtype of BasinsOfAttraction is a convenient structure that stores a representation of the basins of attraction, their associated attractors, and a representation of the domain over which the basin is defined. For example, this domain could be a Grid subtype matching the size of the basins as an array or a set of points sampled from the state space. These fields can be accessed using the extract_basins, extract_attractors, and extract_domain functions respectively.

The map_to_basin function provides interpolation of a point in state space to the basin of attraction it is likely to belong to.

Currently available subtypes:

• ArrayBasinsOfAttraction
• SampledBasinsOfAttraction

All BasinsOfAttraction subtypes can be used with basins_fractions. Additionally, all BasinsOfAttraction subtypes are iterable: basins, attractors = BoA. This was done to ensure backwards compatibility for functions whose original return format was basins, attractors but has since been replaced with a BasinsOfAttraction type.

ArrayBasinsOfAttraction(basins, attractors, grid)

A subtype of BasinsOfAttraction whose basins of attraction are represented by an array::AbstractArray, that has D number of dimensions. The grid prescribes the state space domain that basins cover, and can be anything given to BasinMapRecurrences as a grid, i.e., a tuple of ranges or a Grid subtype. The attractors are the usual form of Attractors.jl, a dictionary labels to StateSpaceSets.

SampledBasinsOfAttraction(basins, attractors, sampled_points)

A subtype of BasinsOfAttraction where the basins are sampled points in the state space. basins are thus a vector::AbstractVector, each entry corresponding to the point in sampled_points. The attractors are the usual form of Attractors.jl, a dictionary labels to StateSpaceSets.

sampled_points can be a StateSpaceSet with the same dimensionality and element type as the attractors, or alternatively a vector of points with the same requirements.

Additional keyword arguments may be specified for use in the construction of a search structure which map_to_basin uses to interpolate state space points to their nearest basin. These arguments are:

• tree: search tree constructor (e.g. KDTree, BallTree).
• metric: distance metric (e.g. Euclidean(), Chebyshev()).
• searchstructure_kwargs...: additional keyword arguments propagated to Neighborhood.searchstructure.

map_to_basin(BoA::BasinOfAttraction, point; kwargs...) → id

Given a point, map_to_basin interpolates to which basin it should belong.

For ArrayBasinsOfAttraction this finds the label of the closest grid cell.

For SampledBasinsOfAttraction this finds the label corresponding to the nearest neighbor using Neighborhood.jl

For developing a new BasinOfAttraction subtype extend the internal function map_to_domain, and ensure that the basins can be indexed by the returned value.

basins_fractions(bmap::BasinMap, ics::InitialConditionsSampler; kwargs...)

Approximate the state space fractions fs of the basins of attraction of a dynamical system by mapping initial conditions to attractors using bmap (which contains a reference to a DynamicalSystem). The fractions are simply the ratios of how many initial conditions ended up at each attractor. Return the fractions as a dictionary mapping basin IDs (integers) to their fractions. If you also want to obtain a vector of labels corresponding to each initial condition, use the function basins_fractions_labels instead.

Initial conditions are sampled using a concrete subtype of InitialConditionsSampler and typically will use RandomICsSampler or PrescribedICs.

Return

The function will always return fractions, which is a dictionary whose keys are the labels given to each attractor (always integers enumerating the different attractors), and whose values are the respective basins fractions. The label -1 is given to any initial condition where bmap could not match to an attractor (this depends on the bmap type).

If ics is a StateSpaceSet the function will also return labels, which is a vector, of equal length to ics, that contains the label each initial condition was mapped to.

See BasinMap for all possible bmap types, and use extract_attractors (after calling basins_fractions) to extract the stored attractors from the bmap. See also convergence_and_basins_fractions.

Keyword arguments

• show_progress = true: Display a progress bar of the process.

basins_fractions(BoA::BasinsOfAttraction [,ids]) → fs::Dict
basins_fractions(basins::AbstractArray [,ids]) → fs::Dict

Calculate the state space fraction of the basins of attraction encoded in basins. The elements of basins are integers, enumerating the attractor that the entry of basins converges to (i.e., like the output of basins_of_attraction). Return a dictionary that maps attractor IDs to their relative fractions. Optionally you may give a vector of ids to calculate the fractions of only the chosen ids (by default ids = unique(basins)).

basins_fractions_labels(bmap::BasinMap, sampler::InitialConditionsSampler; kw...)

Same as basins_fractions but return two outputs: the fractions dictionary and a vector of integers which contains the labels of the provided initial conditions.

basins_of_attraction(bmap::BasinMapRecurrences; show_progress = true) → boa

This is a special method of basins_of_attraction that using recurrences does exactly what is described in the paper by Datseris & Wagemakers (Datseris and Wagemakers, 2022). By enforcing that the internal grid of bmap is the same as the grid of initial conditions to map to attractors, the method can further utilize found exit and attraction basins, making the computation faster as the grid is processed more and more.

The return has type ArrayBasinsOfAttraction, but may be decomposed as basins, attractors = boa ensuring backwards compatibility with the previous return format.

basins_of_attraction(bmap::BasinMap, grid::Tuple) → boa

Compute the full basins of attraction as identified by the given bmap, which includes a reference to a DynamicalSystem and return them along with (perhaps approximated) found attractors contained within the ArrayBasinsOfAttraction structure.

grid is a tuple of ranges defining the grid of initial conditions that partition the state space into boxes with size the step size of each range. For example, grid = (xg, yg) where xg = yg = range(-5, 5; length = 100). The grid has to be the same dimensionality as the state space expected by the integrator/system used in bmap. E.g., a ProjectedDynamicalSystem could be used for lower dimensional projections, etc. A special case here is a PoincareMap with plane being Tuple{Int, <: Real}. In this special scenario the grid can be one dimension smaller than the state space, in which case the partitioning happens directly on the hyperplane the Poincaré map operates on.

basins_of_attraction function is a convenience 5-lines-of-code wrapper which uses the labels returned by basins_fractions and simply assigns them to a full array corresponding to the state space partitioning indicated by grid.

Note that, to ensure backwards compatibility the return type can be decomposed such that basins, attractors = boa.

See also convergence_and_basins_of_attraction.

basins_of_attraction(bmap::BasinMap, sampler::InitialConditionsSampler; kw...) → boa

Compute and return a SampledBasinsOfAttraction object.

The only keyword is show_progress = true.

statespace_sampler(region [, seed = 42]) → sampler, isinside

A function that facilitates sampling points randomly and uniformly in a state space region. It generates two functions:

• sampler is a 0-argument function that when called generates a random point inside a state space region. The point is always a Vector for type stability irrespectively of dimension. Generally, the generated point should be copied if it needs to be stored. (i.e., calling sampler() utilizes a shared vector) sampler is a thread-safe function.
• isinside is a 1-argument function that returns true if the given state space point is inside the region.

The region can be an instance of any of the following types (input arguments if not specified are vectors of length D, with D the state space dimension):

• HSphere(radius::Real, center): points inside the hypersphere (boundary excluded). Convenience method HSphere(radius::Real, D::Int) makes the center a D-long vector of zeros.
• HSphereSurface(radius, center): points on the hypersphere surface. Same convenience method as above is possible.
• HRectangle(mins, maxs): points in [min, max) for the bounds along each dimension.

The random number generator is always Xoshiro with the given seed.

statespace_sampler(grid::NTuple{N, AbstractRange} [, seed])

If given a grid that is a tuple of AbstractVectors, the minimum and maximum of the vectors are used to make an HRectangle region.

InitialConditionsSampler

Data structure deciding how to sample initial conditions during global_continuation. Concerete subtypes are:

• RandomICsSampler
• PrescribedICs
• PerParameterICs

InitialConditionsSampler defines a currently experimental extendable interface based on the internal functions generate_ics, update_sampler!, resampling_required.

length(sampler) returns the number of initial conditions that will be generated by the sampler.

RandomICsSampler(f::Function, N::Int) <: InitialConditionsSampler

Wrapper around a function f, to be called as f() -> u. When called, it generates a random initial condition. The sampler generates overall N initial conditions.

The following convenience signature is also provided

RandomICsSampler(N::Int, args...; kw...)

which propagates args, kw to statespace_sampler and uses the generated sampler as the function f.

PrescribedICs(u0s::AbstractVector) <: InitialConditionsSampler

Wrapper around a container of initial conditions that simply provides u0s as the sampled initial conditions.

PerParameterICs(f, N::Int) <: InitialConditionsSampler

Wrapper around a function f, to be called as f(parameters, N). When used in basins_fractions, it inputs the current_parameters of the dynamical system. When used in global_continuation it inputs the current element of pcurve (which is expected to be a dictionary). The sampler generates overall N initial conditions.

convergence_and_basins_fractions(bmap::BasinMap, ics)

An extension of basins_fractions. Return fs, labels, convergence. The first two are as in basins_fractions, and convergence is a vector containing the time each initial condition took to converge to its attractor. Only usable with mappers that support id = bmap(u0).

See also convergence_time.

Keyword arguments

• show_progress = true: show progress bar.

convergence_and_basins_of_attraction(bmap::BasinMap, grid)

An extension of basins_of_attraction. Return basins, attractors, convergence, with basins, attractors as in basins_of_attraction, and convergence being an array with same shape as basins. It contains the time each initial condition took to converge to its attractor. It is useful to give to shaded_basins_heatmap.

See also convergence_time. Note that this function is not able to be updated with a BasinsOfAttraction return type as the return is an iterable also contains iterations, but array_basins, iterations breaks backwards compatibility.

Keyword arguments

• show_progress = true: show progress bar.