StateElement

A StateElement is a a combination of a value and a space. Under the hood, StateElement subclasses numpy.ndarray; essentially, it adds a layer that checks whether the values are contained in the space (and what to do if not). As a result, many NumPy methods will work.

Instantiating a StateElement is straightforward.

# Value in a Categorical set
x = cat_element(3)
# Discrete value
y = discrete_array_element(low=2, high=5, init=2)
# Continuous Value
z = array_element(
    low=-numpy.ones((2, 2)), high=numpy.ones((2, 2)), out_of_bounds_mode="error"
)

Note

The examples above give the preferred input shape, but StateElement will consider the input as an array and try to viewcast input that does not match expected shape. That means that e.g. x = StateElement(2, discr_space, out_of_bounds_mode="error") is also considered valid input.

StateElement has an out_of_bounds_mode keyword argument (defaults to ‘warning’) that specifies what to do when a value is not contained in the space:

• “error” –> raises a StateNotContainedError

• “warning” –> warns with a StateNotContainedWarning, but accepts the input

• “clip” –> clips the data to force it to belong to the space

• “silent” –> Values not in the space are accepted silently (behavior should become equivalent to numpy.ndarray).

• “raw” –> No data transformation is applied. This is faster than the other options, because the preprocessing of input data is short-circuited. However, this provides no tolerance for misspecified input.

Note

Broad/viewcasting and type casting are applied if necessary to the first four cases if the space has “contains” set to “soft”, but never with “raw”.

Other mechanisms

• You can randomize its values

  
  # Random resets
  x.reset()
  y.reset()
  z.reset()
  
  # Forced resets
  x.reset(value=2)
  y.reset(2)
  z.reset(0.59 * numpy.ones((2, 2)))
  
  
  # forced reset also raise input checks:
  try:
      x.reset(value=5)
  except StateNotContainedError:
      print("raised Error {} as expected".format(StateNotContainedError))
  
  

• You can iterate over them

  # iterating over a continuous space like in Numpy: first over rows, then over columns
  x = array_element(
      init=numpy.array([[0.2, 0.3], [0.4, 0.5]]),
      low=-numpy.ones((2, 2)),
      high=numpy.ones((2, 2)),
  )
  
  for i, _x in enumerate(x):
      for j, _xx in enumerate(_x):
          print(_xx)
  
  # you can't iterate over a discrete set
  x = cat_element(4)
  with pytest.raises(TypeError):
      next(iter(x))
  

• You can compare them. This includes a “hard” comparison, which checks if spaces are equal.

  x = discrete_array_element(init=1, low=1, high=4)
  w = discrete_array_element(init=1, low=1, high=3)
  assert w.equals(x)
  # Hard comparison checks also space
  assert not w.equals(x, "hard")
  

• You can extract values with or without spaces. Extracting the spaces together with the values can be done by a mechanism that abuses the slice notation.

  # CoopIHC abuses Python's indexing mechanism; you can extract values together with spaces
  x = cat_element(3)
  assert x[..., {"space": True}] == x
  assert x[...] == x
  
  x = array_element(
      init=numpy.array([[0.0, 0.1], [0.2, 0.3]]),
      low=-numpy.ones((2, 2)),
      high=numpy.ones((2, 2)),
  )
  assert x[0, 0] == 0.0
  assert x[0, 0, {"space": True}] == array_element(init=0.0, low=-1, high=1)
  

• You can cast values from one space to the other. This includes two modes of casting between discrete and continuous spaces.

  
  # --------------------------- Init viz.
  
  import matplotlib.pyplot as plt
  
  fig = plt.figure()
  axd2c = fig.add_subplot(221)
  axc2d = fig.add_subplot(222)
  axc2c = fig.add_subplot(223)
  axd2d = fig.add_subplot(224)
  
  # --------------------------  Discrete 2 Continuous
  
  _center = []
  _edges = []
  for i in [1, 2, 3]:
      x = discrete_array_element(init=i, low=1, high=3)
      y = array_element(init=i, low=-1.5, high=1.5)
      _center.append(x.cast(y, mode="center").tolist())
      _edges.append(x.cast(y, mode="edges").tolist())
  
  
  axd2c.plot(numpy.array([1, 2, 3]), numpy.array(_center) - 0.05, "+", label="center")
  axd2c.plot(numpy.array([1, 2, 3]), numpy.array(_edges) + 0.05, "o", label="edges")
  axd2c.legend()
  
  # ------------------------   Continuous 2 Discrete
  center = []
  edges = []
  for i in numpy.linspace(-1.5, 1.5, 100):
      x = discrete_array_element(init=i, low=1, high=3)
      y = array_element(init=i, low=-1.5, high=1.5)
  
      ret_stateElem = y.cast(x, mode="center")
      center.append(ret_stateElem.tolist())
  
      ret_stateElem = y.cast(x, mode="edges")
      edges.append(ret_stateElem.tolist())
  
  
  axc2d.plot(
      numpy.linspace(-1.5, 1.5, 100), numpy.array(center) - 0.05, "+", label="center"
  )
  axc2d.plot(
      numpy.linspace(-1.5, 1.5, 100), numpy.array(edges) + 0.05, "o", label="edges"
  )
  axc2d.legend()
  
  
  # ------------------------- Continuous2Continuous
  
  output = []
  for i in numpy.linspace(-1, 1, 100):
      x = array_element(
          init=numpy.full((2, 2), i),
          low=numpy.full((2, 2), -1),
          high=numpy.full((2, 2), 1),
          dtype=numpy.float32,
      )
      y = array_element(
          low=numpy.full((2, 2), 0), high=numpy.full((2, 2), 4), dtype=numpy.float32
      )
      output.append(x.cast(y)[0, 0].tolist())
  
  axc2c.plot(numpy.linspace(-1, 1, 100), numpy.array(output), "-")
  
  # -------------------------- Discrete2Discrete
  
  
  output = []
  for i in [1, 2, 3, 4]:
      x = discrete_array_element(init=i, low=1, high=4)
      y = discrete_array_element(init=11, low=11, high=14)
      output.append(x.cast(y).tolist())
  
  axd2d.plot([1, 2, 3, 4], output, "+")
  
  
  # ----------------------- show viz
  plt.tight_layout()
  # plt.show()