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)[source]

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)[source]

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)[source]

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__()[source]

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)[source]

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)[source]

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.