Skip to content

Commit

Permalink
Update docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
@pmrv
pmrv committed Oct 9, 2023
1 parent 0ccab4e commit 709a767
Showing 1 changed file with 50 additions and 18 deletions.
68 changes: 50 additions & 18 deletions pyiron_base/storage/flattenedstorage.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,15 +121,15 @@ class FlattenedStorage(HasHDF):
>>> store.get_array("sum", 2)
57
Finally you may add multiple arrays in one call to :method:`.add_chunk` by using keyword arguments
Finally you may add multiple arrays in one call to :meth:`.add_chunk` by using keyword arguments
>>> store.add_chunk(4, even=[14, 16, 18, 20], odd=[13, 15, 17, 19], sum=119)
>>> store.get_array("sum", 3)
119
>>> store.get_array("even", 3)
array([14, 16, 18, 20])
It is usually not necessary to call :method:`.add_array` before :method:`.add_chunk`, the type of the array will be
It is usually not necessary to call :meth:`.add_array` before :meth:`.add_chunk`, the type of the array will be
inferred in this case.
If you skip the `frame` argument to :meth:`.get_array` it will return a flat array of all the values for that array
Expand All @@ -140,9 +140,9 @@ class FlattenedStorage(HasHDF):
>>> store.get_array("even")
array([ 0, 4, 6, 8, 10, 12, 14, 16, 18, 20])
Arrays may be of more complicated shape, too, see :method:`.add_array` for details.
Arrays may be of more complicated shape, too, see :meth:`.add_array` for details.
Use :method:`.copy` to obtain a deep copy of the storage, for shallow copies using the builting `copy.copy` is
Use :meth:`.copy` to obtain a deep copy of the storage, for shallow copies using the builting `copy.copy` is
sufficient.
>>> copy = store.copy()
Expand All @@ -153,7 +153,7 @@ class FlattenedStorage(HasHDF):
>>> copy["even"]
array([0, 4, 6, 8, 10, 12])
Storages can be :method:`.split` and :method:`.join` again as long as their internal chunk structure is consistent,
Storages can be :meth:`.split` and :meth:`.join` again as long as their internal chunk structure is consistent,
i.e. same number of chunks and same chunk lengths. If this is not the case a `ValueError` is raised.
>>> even = store.split(["even"])
Expand All @@ -163,11 +163,11 @@ class FlattenedStorage(HasHDF):
False
>>> odd = store.split(["odd"])
:method:`.join` adds new arrays to the storage it is called on in-place. To leave it unchanged, simply call copy
:meth:`.join` adds new arrays to the storage it is called on in-place. To leave it unchanged, simply call copy
before join.
>>> both = even.copy().join(odd)
Chunks may be given string names, either by passing `identifier` to :method:`.add_chunk` or by setting to the
Chunks may be given string names, either by passing `identifier` to :meth:`.add_chunk` or by setting to the
special per chunk array "identifier"
>>> store.set_array("identifier", 1, "second")
Expand Down Expand Up @@ -300,7 +300,7 @@ def find_chunk(self, identifier):
Return integer index for given identifier.
Args:
identifier (str): name of chunk previously passed to :method:`.add_chunk`
identifier (str): name of chunk previously passed to :meth:`.add_chunk`
Returns:
int: integer index for chunk
Expand Down Expand Up @@ -443,7 +443,7 @@ def get_array(self, name, frame=None):
Args:
name (str): name of the array to fetch
frame (int, str, optional): selects structure to fetch, as in :method:`.get_structure()`, if not given
frame (int, str, optional): selects structure to fetch, as in :meth:`.get_structure()`, if not given
return a flat array of all values for either all chunks or elements
Returns:
Expand Down Expand Up @@ -475,7 +475,7 @@ def get_array_ragged(self, name: str) -> np.ndarray:
Return elements of array `name` in all chunks. Values are returned in a ragged array of dtype=object.
If `name` specifies a per chunk array, there's nothing to pad and this method is equivalent to
:method:`.get_array`.
:meth:`.get_array`.
Args:
name (str): name of array to fetch
Expand All @@ -497,10 +497,10 @@ def get_array_filled(self, name: str) -> np.ndarray:
Return elements of array `name` in all chunks. Arrays are padded to be all of the same length.
The padding value depends on the datatpye of the array or can be configured via the `fill` parameter of
:method:`.add_array`.
:meth:`.add_array`.
If `name` specifies a per chunk array, there's nothing to pad and this method is equivalent to
:method:`.get_array`.
:meth:`.get_array`.
Args:
name (str): name of array to fetch
Expand Down Expand Up @@ -535,7 +535,7 @@ def set_array(self, name, frame, value):
Args:
name (str): name of array to set
frame (int, str): selects structure to set, as in :method:`.get_strucure()`
frame (int, str): selects structure to set, as in :meth:`.get_strucure()`
value: value (for per chunk) or array of values (for per element); type and shape as per :meth:`.hasarray()`.
Raises:
Expand Down Expand Up @@ -601,7 +601,7 @@ def __delitem__(self, index):

def has_array(self, name):
"""
Checks whether an array of the given name exists and returns meta data given to :method:`.add_array()`.
Checks whether an array of the given name exists and returns meta data given to :meth:`.add_array()`.
>>> container.has_array("energy")
{'shape': (), 'dtype': np.float64, 'per': 'chunk'}
Expand All @@ -613,7 +613,7 @@ def has_array(self, name):
Returns:
None: if array does not exist
dict: if array exists, keys corresponds to the shape, dtype and per arguments of :method:`.add_array`
dict: if array exists, keys corresponds to the shape, dtype and per arguments of :meth:`.add_array`
"""
if name in self._per_element_arrays:
a = self._per_element_arrays[name]
Expand Down Expand Up @@ -656,7 +656,7 @@ def sample(
Returns:
:class:`.FlattenedStorage` or subclass: storage with the selected chunks
"""
new = self.__class__()
new = type(self)()
for k, a in self._per_chunk_arrays.items():
if k not in ("start_index", "length", "identifier"):
new.add_array(k, shape=a.shape[1:], dtype=a.dtype, per="chunk")
Expand Down Expand Up @@ -718,9 +718,19 @@ def join(
Args:
store (:class:`.FlattenedStorage`): storage to join
lsuffix, rsuffix (str, optional): if either are given rename *all* arrays by appending the suffices to the
array name; `lsuffix` for arrays in this storage, `rsuffix` for arrays in
the added storage; in this case arrays are no longer available under the
old name
Returns:
:class:`.FlattenedStorage`: self
Raise:
ValueError: if the two stores do not have the same number of chunks
ValueError: if the two stores do not have equal chunk lengths
ValueError: if lsuffix and rsuffix are equal and different from ""
ValueError: if the stores share array names but `lsuffix` and `rsuffix` are not given
"""
if len(self) != len(store):
raise ValueError(
Expand Down Expand Up @@ -751,13 +761,17 @@ def join(
for k, a in store._per_element_arrays.items():
if k in self._per_element_arrays and rename:
self._per_element_arrays[k + lsuffix] = self._per_element_arrays[k]
if lsuffix != "":
del self._per_element_arrays[k]
k += rsuffix
self._per_element_arrays[k] = a

for k, a in store._per_chunk_arrays.items():
if k not in ("start_index", "length", "identifier"):
if k in self._per_chunk_arrays and rename:
self._per_chunk_arrays[k + lsuffix] = self._per_chunk_arrays[k]
if lsuffix != "":
del self._per_chunk_arrays[k]
k += rsuffix
self._per_chunk_arrays[k] = a

Expand Down Expand Up @@ -791,10 +805,10 @@ def add_chunk(self, chunk_length, identifier=None, **arrays):
>>> container.get_array("pressure", 2).shape
(3, 3)
.. attention: Edge-case!
.. attention:: Edge-case!
This will not work when the chunk length is also 1 and the array does not exist yet! In this case the array
will be assumed to be per element and there is no way around explicitly calling :method:`.add_array()`.
will be assumed to be per element and there is no way around explicitly calling :meth:`.add_array()`.
Args:
Expand Down Expand Up @@ -857,6 +871,22 @@ def add_chunk(self, chunk_length, identifier=None, **arrays):
# return last_chunk_index, last_element_index

def extend(self, other: "FlattenedStorage"):
"""
Add chunks from `other` to this storage.
Afterwards the number of chunks and elements are the sum of the respective previous values.
If `other` defines new arrays or doesn't define some of the arrays they are padded by the fill values.
Args:
other (:class:`.FlattenedStorage`): other storage to add
Raises:
ValueError: if fill values between both storages are not compatible
Returns:
FlattenedStorage: return this storage
"""
self._check_compatible_fill_values(other=other)

combined_num_chunks = self.num_chunks + other.num_chunks
Expand Down Expand Up @@ -899,6 +929,8 @@ def extend(self, other: "FlattenedStorage"):
self.current_chunk_index = self.num_chunks
self.current_element_index = self.num_elements

return self

def _check_compatible_fill_values(self, other: "FlattenedStorage"):
"""
Check if fill values of 2 FlattenedStorages match to prevent errors due to wrong fill values,
Expand Down

0 comments on commit 709a767

Please sign in to comment.