py21cmfast.wrapper.arrays.Array
===============================

.. py:class:: py21cmfast.wrapper.arrays.Array

   
   A flexible array management class providing  state tracking and initialization capabilities.

   The Array class supports dynamic array creation, caching, and state management with
   immutable semantics.The class allows for creating arrays with configurable shape,
   data type, initialization function, and optional caching backend.
   It provides methods for initializing, setting values, removing values, writing to
   disk, and loading from disk while maintaining a consistent state.

   .. note:: One deliberate exception to this immutability: accessing a purged
             array's data directly (e.g. `arr.mean()`, `np.asarray(arr)`, or any
             other attribute not defined on this class) - rather than through
             `OutputStruct.get()` - transparently loads it from disk and, unless
             `config["CACHE_ARRAYS_ON_ACCESS"]` is set to False, caches the result
             by mutating `_value`, `state` and `cache_backend` on this instance in
             place (bypassing `frozen=True`). Any other reference to the same
             `Array` object will observe that mutation. All other methods on this
             class remain purely functional, returning a new instance rather than
             mutating `self`.

   :ivar shape: Dimensions of the array.
   :ivar dtype: Data type of the array (default is float).
   :ivar state: Current state of the array.
   :ivar initfunc: Function used for array initialization (default is np.zeros).
   :ivar _value: Actual array data, or `None` if it is not currently in memory (e.g. it has
                 been purged to disk). Private: read the data off the `Array` itself, or via
                 `OutputStruct.get()`, so that a purged array is transparently reloaded.
   :ivar cache_backend: Optional backend for disk caching.

   .. rubric:: Examples

   # Create an array with specific shape and initialize
   arr = Array(shape=(10, 10))
   initialized_arr = arr.initialize()

   # Set a value and write to disk
   arr = arr.with_value(np.random.rand(10, 10))
   arr = arr.written_to_disk(backend)















   ..
       !! processed by numpydoc !!

   .. py:method:: computed() -> Self

      
      Set the array to a given value and return a new Array.
















      ..
          !! processed by numpydoc !!


   .. py:method:: initialize()

      
      Initialize the array to its initial/default allocated state.
















      ..
          !! processed by numpydoc !!


   .. py:method:: loaded_from_disk(backend: CacheBackend | None = None) -> Self

      
      Load values for the array from a cache backend, and return a new instance.
















      ..
          !! processed by numpydoc !!


   .. py:method:: purged_to_disk(backend: CacheBackend | None) -> Self

      
      Move the array data to disk and return a new object with correct state.
















      ..
          !! processed by numpydoc !!


   .. py:method:: trimmed(trimmed_shape: tuple[int]) -> Self

      
      Return a new Array with the same data but a different shape, by slicing the original array.
















      ..
          !! processed by numpydoc !!


   .. py:method:: with_value(val: numpy.ndarray) -> Self

      
      Set the array to a given value and return a new Array.
















      ..
          !! processed by numpydoc !!


   .. py:method:: without_value() -> Self

      
      Remove the allocated data from the array.
















      ..
          !! processed by numpydoc !!


   .. py:method:: written_to_disk(backend: CacheBackend | None) -> Self

      
      Write the array to disk and return a new object with correct state.
















      ..
          !! processed by numpydoc !!


   .. py:attribute:: cache_backend


   .. py:attribute:: dtype


   .. py:attribute:: initfunc


   .. py:attribute:: shape


   .. py:attribute:: state


   .. py:property:: value
      :type: numpy.ndarray


      
      Deprecated accessor for the array's data.

      `.value` used to be the raw in-memory slot, which meant it read as `None` for
      an array that had been purged to disk - a silent wrong answer, since the data
      was still perfectly available. It now resolves, loading from disk if needed.

      It is deprecated because it no longer has a job to do: an `OutputStruct`'s
      field attribute (or `OutputStruct.get()`) already gives you the data as a
      plain numpy array, so `ic.hires_density` is what you want. This class is the
      *manager* for that data, reached via `OutputStruct.arrays[...]`, and is only
      of interest when you care about where the data lives rather than what it is.















      ..
          !! processed by numpydoc !!