# Class AttractorFamily

java.lang.Object
uk.ac.starlink.ttools.scheme.AttractorFamily

public abstract class AttractorFamily extends Object
Defines an interface and some implementations for a family of (potentially) strange attractors.

Since:
  21 Jul 2020
Author:
  Mark Taylor

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`AttractorFamily.Attractor`
Defines an unbounded sequence of points, that may represent an attractor.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final AttractorFamily`
`CLIFFORD`
Clifford attractors; 2d, with four parameters.
`static final AttractorFamily`
`HENON`
Henon attractors; 2d, with three parameters (quite boring).
`static final AttractorFamily`
`RAMPE`
Rampe attractors; 3d, wit six parameters.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`AttractorFamily(String name, int ndim, int nparam, double maxAbsParam, double fillThresh)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`AttractorFamily.Attractor`
`createAttractor(double[] params, double[] seed)`
Creates an attractor in this family by supplying numeric parameters.
`AttractorFamily.Attractor`
`createAttractor(Random rnd)`
Creates a random attractor in this family.
`abstract UnaryOperator<double[]>`
`createOperator(double[] params)`
Returns the operator which produces the next ndim-element output point from the previous one.
`int`
`getDimCount()`
Returns the dimensionality of points in the sequence generated by attractors from this family.
`abstract String`
`getDocUrl()`
Returns a URL on the WWW at which additional or background information about this attractor family may be found.
`abstract String[]`
`getEquations()`
Returns a list of lines giving a textual representation of the iteration formula used to generate attractors.
`abstract double[][]`
`getExamples()`
Returns a hard coded list of attractor parameter arrays that represent interesting members of this family.
`double`
`getFillThreshold()`
Returns a guideline value for the space filling factor which represents an interesting (strange) attractor from this family.
`double`
`getMaxAbsParam()`
The maximum absolute value recommended for each of the input values (which should therefore be in the range [-maxAbsParam,+maxAbsParam]).
`String`
`getName()`
Returns the name of this family.
`int`
`getParamCount()`
Returns the number of parameters required to produce an attractor instance.
`static double`
`getSpaceFraction(AttractorFamily.Attractor att, int nbin)`
Calculates a measure of the proportion of the N-dimensional space defined by the bounds of an attractor.
`static Stream<AttractorFamily.Attractor>`
`getStrangeAttractors(AttractorFamily family)`
Utility/example method to create a stream of strange attractors in a given family.
`static double[]`
`randoms(Random rnd, int n, double absmax)`
Returns a fixed size array containing random numbers suitable for use as attractor parameters.

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### CLIFFORD

public static final AttractorFamily CLIFFORD
Clifford attractors; 2d, with four parameters.

See Also:
  - https://examples.pyviz.org/attractors/attractors.html

### RAMPE

public static final AttractorFamily RAMPE
Rampe attractors; 3d, wit six parameters.

See Also:
  - https://softologyblog.wordpress.com/2009/10/19/3d-strange-attractors/

### HENON

public static final AttractorFamily HENON
Henon attractors; 2d, with three parameters (quite boring).

See Also:
  - https://en.wikipedia.org/wiki/H%C3%A9non_map

## Constructor Details

### AttractorFamily

protected AttractorFamily(String name, int ndim, int nparam, double maxAbsParam, double fillThresh)
Constructor.

Parameters:
  `name` - name of family
  `ndim` - dimensionality of output points
  `nparam` - number of numerical parameters required to define an attractor
  `maxAbsParam` - the maximum absolute recommended value of each of the numerical parameters
  `fillThresh` - guideline space filling factor above which attractors in this family look interesting (strange)

## Method Details

### getName

public String getName()
Returns the name of this family.

Returns:
  name

### getDimCount

public int getDimCount()
Returns the dimensionality of points in the sequence generated by attractors from this family.

Returns:
  output space dimensionality

### getParamCount

public int getParamCount()
Returns the number of parameters required to produce an attractor instance.

Returns:
  number of required numeric parameters

### getMaxAbsParam

public double getMaxAbsParam()
The maximum absolute value recommended for each of the input values (which should therefore be in the range [-maxAbsParam,+maxAbsParam]).

Returns:
  range for numeric parameters

### getFillThreshold

public double getFillThreshold()
Returns a guideline value for the space filling factor which represents an interesting (strange) attractor from this family. Many or most attractors in a given family are quite boring (not strange).

Returns:
  approximate space fraction threshold for strangeness
See Also:
  - `getSpaceFraction(AttractorFamily.Attractor, int)`

### getEquations

public abstract String[] getEquations()
Returns a list of lines giving a textual representation of the iteration formula used to generate attractors. The expectation is that this will be displayed in a fixed-width font, with one element per display line.

Returns:
  textual representation of iteration equations

### getDocUrl

public abstract String getDocUrl()
Returns a URL on the WWW at which additional or background information about this attractor family may be found.

Returns:
  documentation URL, or null if none known

### createOperator

public abstract UnaryOperator<double[]> createOperator(double[] params)
Returns the operator which produces the next ndim-element output point from the previous one.

Parameters:
  `params` - nparam-element list of numeric parameters defining the attractor
Returns:
  point generator function

### createAttractor

public AttractorFamily.Attractor createAttractor(double[] params, double[] seed)
Creates an attractor in this family by supplying numeric parameters.

Parameters:
  `params` - nparam-element array of numeric parameters
  `seed` - initial point for iteration, or null for default
Returns:
  attractor

### createAttractor

public AttractorFamily.Attractor createAttractor(Random rnd)
Creates a random attractor in this family.

Parameters:
  `rnd` - random seed
Returns:
  attractor

### getExamples

public abstract double[][] getExamples()
Returns a hard coded list of attractor parameter arrays that represent interesting members of this family. Suitable examples can be generated by running `getStrangeAttractors(AttractorFamily)`. This list should contain at least one entry.

Returns:
  example parameter arrays for strange attractors

### randoms

public static double[] randoms(Random rnd, int n, double absmax)
Returns a fixed size array containing random numbers suitable for use as attractor parameters. The values are reasonably "round", which means they can be written down without a lot of significant figures.

Parameters:
  `rnd` - random seed
  `n` - required size of output array
  `absmax` - absolute maximum value
Returns:
  n-element array of values each in the range [-absmax,+absmax]

### getSpaceFraction

public static double getSpaceFraction(AttractorFamily.Attractor att, int nbin)
Calculates a measure of the proportion of the N-dimensional space defined by the bounds of an attractor. This is a useful value for identifying "interesting" attractors; boring/non-strange ones may collapse down to a small number of points or lines, but ones which return a high value probably look nice.

Of course the actual proporition for a finite number of points is effectively zero, but we bin the space up into a regular grid and count how many of the grid elements are hit during iteration.

Parameters:
  `att` - attractor to characterise
  `nbin` - number of bins along each axis
Returns:
  proportion of bins that are covered by a sequence of iterations

### getStrangeAttractors

public static Stream<AttractorFamily.Attractor> getStrangeAttractors(AttractorFamily family)
Utility/example method to create a stream of strange attractors in a given family.

Parameters:
  `family` - attractor family
Returns:
  stream of strange attractors