ifstype.ifs

This module contains core classes and methods for use in the simulation of any iterated function system.

Public module attributes:

class ifstype.AffineFunc(r: numbers.Real = Fraction(1, 1), d: numbers.Real = Fraction(0, 1))[source]

An AffineFunc is a real-valued affine function f(x)=r*x+d.

This class is an immutable storage class. When called without arguments, it defaults to the identity function.

Core attributes:

Methods for function properties:

Methods for behaviour as a function:

r

The affine factor

d

The translation factor

fixed_point() → numbers.Real[source]

Compute the point which the affine function fixes.

>>> aff = AffineFunc(Fraction(2),Fraction(3))
>>> aff.fixed_point()
Fraction(-3, 1)
>>> aff(aff.fixed_point())
Fraction(-3, 1)

The affine factor must have absolute value not equal to 1.

Raises

ValueError – if linear coefficient is equal to 1

Returns

p such that f(p) == p.

interval(initial_iv: ifstype.exact.interval.Interval = Interval(a=Fraction(0, 1), b=Fraction(1, 1))) → ifstype.exact.interval.Interval[source]

Compute the set image f(initial_iv)={f(x):x in initial_iv} corresponding to the function.

>>> aff = AffineFunc(-Fraction(1,2),Fraction(3,4))
>>> aff.interval()
Interval(a=Fraction(1, 4), b=Fraction(3, 4))
Parameters

initial_iv – interval to compute image of

Returns

image of the interval

__call__(x: numbers.Real) → numbers.Real[source]

Use the class as a python function.

>>> aff = AffineFunc(Fraction(2),Fraction(3))
>>> aff(Fraction(1,2))
Fraction(4, 1)
Parameters

x – call value

Returns

result of applying function to x

compose(g: ifstype.ifs.AffineFunc) → ifstype.ifs.AffineFunc[source]

Compute the affine function resulting from right composition with the affine function g.

>>> aff = AffineFunc(Fraction(2),Fraction(1,3))
>>> afg = AffineFunc(Fraction(2),Fraction(3))
>>> aff.compose(afg)
AffineFunc(r=Fraction(4, 1), d=Fraction(19, 3))
Parameters

g – any affine function

Returns

a new affine function instance f(g(x))

inverse() → ifstype.ifs.AffineFunc[source]

Compute the inverse function of the linear map.

Requires that r is non-zero.

>>> aff = AffineFunc(Fraction(2),Fraction(1,3))
AffineFunc(r=Fraction(1, 2), d=Fraction(-1, 6))
Returns

a new affine function instance g(x) such that g(f(x)=f(g(x))=x

Raises

ZeroDivisionError – if r is zero

class ifstype.IFS(funcs: Sequence[ifstype.ifs.AffineFunc])[source]

A class representing an iterated function system such that the convex hull of the invariant compact set is [0,1].

After initialization, the instance has the following attributes:

The following methods are also defined:

funcs

Tuple of contraction functions associated to the IFS.

probs

Tuple of symbolic probabilities ifstype.exact.SymbolicElement, one for each associated to each contraction function.

If probabilities is set with a sequence of real numbers, they must be strictly greater than 0 and sum to 1

Setter

Associate numeric values to the probabilities which sum to 1.

__init__(funcs: Sequence[ifstype.ifs.AffineFunc]) → None[source]

Initialize iterated function system instance.

The funcs argument is a list of AffineFunc instances with linear factor having absolute value strictly between 0 and 1.

Warning

The funcs return value of the undecorated function may not be equal to the IFS.funcs attribute, since funcs is sorted and normalized to have invariant convex hull [0,1].

Raises

ValueError – if the linear coefficients r do not have absolute value strictly between 0 and 1

Parameters

funcs – a sequence of AffineFunc instances

__str__() → str[source]

Return user-readable string representation of the iterated function system.

Returns

string representation

extend(aff_iterable: Iterable[ifstype.ifs.AffineFunc], with_prob: bool = False) → Union[AbstractSet[Tuple[ifstype.exact.symbolic.SymbolicElement, ifstype.ifs.AffineFunc, ifstype.ifs.AffineFunc]], AbstractSet[ifstype.ifs.AffineFunc]][source]

Return a generator of extensions of elements of aff_iterable by all possible functions in the IFS.

Chains the generator where for each function g of aff_iterable and f of the instance variable f, we compute g.compose(f).

If with_prob is True, the elements of the iterables are tuples (p,aff_init,aff_res) where p is the symbolic probability associated with the function, aff_init is the initial affine function, and aff_res is the resulting affine function after composing with some element of funcs.

Parameters

  • aff_iterable – an iterable of AffineFunc instances

  • with_prob – boolean to return additional information.

Returns

an iterable of all extensions

invariant_convex_hull() → ifstype.exact.interval.Interval[source]

Compute the convex hull of the invariant set K.

The algorithm used is adapted from from József Vass’ paper, Section 3.2, in https://arxiv.org/abs/1502.03788.

Returns

closed interval convex hull

@ifstype.ifs_family(ifs_func: Callable[[...], Sequence[ifstype.ifs.AffineFunc]]) → Callable[[...], ifstype.ifs.IFS][source]

Convenience decorator to construct families of iterated function systems parametrized by some set of values.

Used to decorate functions of the form:

def ifs(probs=def_p, a_1=def_1, ..., a_n=def_n):
    return [AffineFunc(...), ..., AffineFunc(...)]

where a_1,...,a_n are arbitrary parameter names, arbitrary default values def_1,...,def_n for the parameters, and def_p default argument for probabilities (see IFS.probs). The arguments must all be specified as keyword arguments. The decorated function has the same keyword arguments and returns an IFS instance from the corresponding probabilities and contraction functions.

Warning

The funcs return value of the undecorated function may not be equal to the IFS.funcs attribute, since funcs is sorted and normalized to have invariant convex hull [0,1].

Parameters

ifs_func – the function being decorated

Returns

decorated function

class ifstype.ifs.Neighbour(r: numbers.Real = Fraction(1, 1), d: numbers.Real = Fraction(0, 1))[source]

Bases: ifstype.ifs.AffineFunc

A neighbour is a special type of normalized affine function, used to represent a neighbour of a net interval. Neighbours have a fixed order which is used when computing transition matrices.

This class is an immutable storage class.

Methods for creation:

Convenience attributes:

a

The a descriptor of the neighbour.

L

The L descriptor of the neighbour.

classmethod from_aff(aff: ifstype.ifs.AffineFunc, interval: ifstype.exact.interval.Interval) → ifstype.ifs.Neighbour[source]

Create the neighbour corresponding to aff by normalizing against interval.

Parameters

  • aff – the affine function

  • interval – the interval

Returns

the corresponding neighbour

class ifstype.ifs.NeighbourSet(neighbours=(Neighbour(r=Fraction(1, 1), d=Fraction(0, 1)), ))[source]

A neigbour set represents a set of unique neighbours.

This class is an immutable storage class.

Attributes:

Iteration and containment:

Canonical string representation:

Convenince methods:

  • maximal_nbs()

  • nonmaximal_nbs()

  • remove_nb()

neighbours

the set of neighbours

lmax

The maximum of the absolute value of the affine factor among neighbours.

__iter__() → Iterable[ifstype.ifs.Neighbour][source]

An iterable returning the neighbours. The neighbours are not iterated in any particular order. See sorted_iter() to get the neighbours in a fixed order.

Returns

the neighbour iterable

__str__() → str[source]

Return a canonical string representation of the neighbour set. Assuming that the string representations for the coefficients of the neighbour functions are unique, the strings for neighbours are the same if and only if the neighbour sets are equal.

Returns

the string representation

__contains__(nb: ifstype.ifs.Neighbour) → bool[source]

Check if a neighbour is contained in the neighbour set

Parameters

nb – the neighbour

Returns

True if and only if the neighbour is in the neighbour set.

class ifstype.ifs.NetInterval(a: numbers.Real = Fraction(0, 1), b: numbers.Real = Fraction(1, 1), alpha: numbers.Real = Fraction(2, 1), nb_set: ifstype.ifs.NeighbourSet = NeighbourSet(neighbours=frozenset({Neighbour(r=Fraction(1, 1), d=Fraction(0, 1))})))[source]

Bases: ifstype.exact.interval.Interval

A special interval type representing a net interval of generation alpha. This contains the interval information, as well as the neighbour set.

In addition to the attributes and methods inherited from the ifstype.exact.Interval base class, a net interval also has the following attributes and methods:

Attributes:

  • alpha

  • nb_set

Methods for creation:

Methods for computation with net intervals:

classmethod from_funcs(a: numbers.Real, b: numbers.Real, alpha: numbers.Real, funcs: Iterable[ifstype.ifs.AffineFunc]) → ifstype.ifs.NetInterval[source]

Compute the neighbour set of the net interval given an iterable of (not necessarily distinct) affine functions S such that S([0,1]) contains [a,`b`].

Returns

the net interval

transition_gen() → numbers.Real[source]

Compute the largest generation less that alpha for which the net interval is no longer a valid.

Returns

the transition generation

normalization_func() → ifstype.ifs.AffineFunc[source]

Compute the unique affine function S such that S([0,1]) is equal to the net interval.

Returns

the affine function

containing_funcs() → Iterable[ifstype.ifs.AffineFunc][source]

Compute an iterable of functions which correspond to the neighbours in the neighbour set of the net interval. Each affine function generates a distinct neighbour of the net interval.

Returns

an iterable of affine functions

class ifstype.ifs.TransitionMatrix(double_list)[source]

Bases: ifstype.exact.symbolic.SymbolicMatrix

A transition matrix is a special class used to represent the transition matrix associated to an edge in the transition graph. In addition to being a SymbolicMatrix, the transition matrix also remembers the neighbours which correspond to the rows and columns

Methods not inherited from ifstype.exact.SymbolicMatric:

pos_row() → bool[source]

Check if the matrix has the positive row property, in other words that each row contains a non-zero entry.

Returns

True if and only if it has the positive row property.

spectral_radius()

…