State Space

A fundamental property of networks is their state space. The StateSpace class provides a type for representing such a state space. It has anumber of convenient properties, in particular

1. it is iterable, StateSpace.__iter__()
2. you can ask if it contains a particular state, StateSpace.__contains__()
3. it can StateSpace.encode() states as integers, and StateSpace.decode() integers into states

All of this together facilitates the clean implementation of many of the core functions of neet.

API Documentation

class neet.statespace.StateSpace(spec, base=None)

StateSpace represents the state space of a network model. It may be either uniform, i.e. all nodes have the same base, or non-uniform.

__contains__(states)

Determine if a state is in the state space

Examples:

>>> state_space = StateSpace(3)
>>> [0, 0, 0] in state_space
True
>>> [0, 0] in state_space
False
>>> [1, 2, 1] in state_space
False

>>> [0, 2, 1] in StateSpace([2, 3, 2])
True
>>> [0, 1] in StateSpace([2, 2, 3])
False
>>> [1, 1, 6] in StateSpace([2, 3, 4])
False

Parameters:states – the one-dimensional sequence of node states Returns:True if the states are valid

__init__(spec, base=None)

Initialize the state spec in accordance with the provided spec and base base.

Examples of Uniform State Spaces:

>>> spec = StateSpace(5)
>>> (spec.is_uniform, spec.ndim, spec.base)
(True, 5, 2)
>>> spec = StateSpace(3, base=3)
>>> (spec.is_uniform, spec.ndim, spec.base)
(True, 3, 3)
>>> spec = StateSpace([2, 2, 2])
>>> (spec.is_uniform, spec.ndim, spec.base)
(True, 3, 2)

Examples of Non-Uniform State Spaces:

>>> spec = StateSpace([2, 3, 4])
>>> (spec.is_uniform, spec.base, spec.ndim)
(False, [2, 3, 4], 3)

Parameters:

• spec (int or list) – the number of nodes or an array of node bases
• base – the base of the network nodes (ignored if spec is a list)

Raises:

• TypeError – if spec is neither an int nor a list of ints
• TypeError – if base is neither None nor an int
• ValueError – if base is negative or zero
• ValueError – if any element of spec is negative or zero
• ValueError – if spec is empty

__iter__()

Iterate over the states in the state space

Examples of Boolean Spaces

>>> list(StateSpace(1))
[[0], [1]]
>>> list(StateSpace(2))
[[0, 0], [1, 0], [0, 1], [1, 1]]
>>> list(StateSpace(3))
[[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0], [0, 0, 1], [1, 0, 1], [0, 1, 1], [1, 1, 1]]

Examples of Non-Boolean Spaces

>>> list(StateSpace(1, base=3))
[[0], [1], [2]]
>>> list(StateSpace(2, base=4))
[[0, 0], [1, 0], [2, 0], [3, 0], [0, 1], [1, 1], [2, 1], [3, 1], [0, 2], [1, 2], [2, 2], [3, 2], [0, 3], [1, 3], [2, 3], [3, 3]]

Examples of Non-Uniform Spaces

>>> list(StateSpace([1,2,3]))
[[0, 0, 0], [0, 1, 0], [0, 0, 1], [0, 1, 1], [0, 0, 2], [0, 1, 2]]
>>> list(StateSpace([3,4]))
[[0, 0], [1, 0], [2, 0], [0, 1], [1, 1], [2, 1], [0, 2], [1, 2], [2, 2], [0, 3], [1, 3], [2, 3]]

Yields:each possible state in the state space

base

Get the base of each direction of the state space.

If the state space is not uniform, the result is a list of bases (one for each dimension). Otherwise, the result is an integer.

Returns:a list of bases, one for each dimension

decode(encoded)

Decode an integer into a state in accordance with the state space.

Examples:

>>> space = StateSpace(3)
>>> list(space)
[[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0], [0, 0, 1], [1, 0, 1], [0, 1, 1], [1, 1, 1]]
>>> [space.decode(x) for x in range(space.volume)]
[[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0], [0, 0, 1], [1, 0, 1], [0, 1, 1], [1, 1, 1]]

>>> space = StateSpace([2,3])
>>> list(space)
[[0, 0], [1, 0], [0, 1], [1, 1], [0, 2], [1, 2]]
>>> [space.decode(x) for x in range(space.volume)]
[[0, 0], [1, 0], [0, 1], [1, 1], [0, 2], [1, 2]]

Parameters:encoded (int) – the encoded state Returns:the decoded state as a list

encode(state)

Encode a state as an integer consistent with the state space. The encoding is such that, for example, the state [1, 0, 0] will correspond to 1; the state [1, 1, 0] will correspond to 3.

Examples:

>>> space = StateSpace(3, base=2)
>>> [space.encode(s) for s in space]
[0, 1, 2, 3, 4, 5, 6, 7]

>>> space = StateSpace([2,3,4])
>>> [space.encode(s) for s in space]
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]

Parameters:state (list) – the state to encode Returns:a unique integer encoding of the state Raises:ValueError – if state has an incorrect length

is_uniform

Get whether every direction in the state space has the same base.

ndim

Get the dimensionality of the state space.

volume

Get the volume of the state space.