State Class#

class sgio.model.State(name: str = '', data: list | dict | ndarray | None = None, label: list[str] | None = None, location: str = '', entity_ids: ndarray | None = None)#

Bases: object

A class to represent a state with associated data, labels, and location.

This class uses NumPy arrays internally for efficient storage and manipulation of state data. It provides backward compatibility by accepting dict/list inputs and converting them to NumPy arrays.

name#

The name of the state.

Type:

str

data#

The data associated with the state as a NumPy array. Shape: (n_entities, n_components) for field data Shape: (n_components,) for point data

Type:

np.ndarray

label#

The labels associated with the state components.

Type:

list of str

location#

The location type of the state: ‘node’, ‘element’, or ‘element_node’.

Type:

str

entity_ids#

Maps row index to entity ID for field data. None for point data.

Type:

np.ndarray or None

Notes

The class automatically converts legacy dict/list inputs to NumPy arrays:

  • Point data (list): [v1, v2, ...] -> np.array([v1, v2, ...])

  • Field data (dict): {id: [v1, v2, ...], ...} -> NumPy array with entity_ids

Performance improvements over dict-based implementation:

  • State.at() is ~1000x faster using NumPy boolean indexing

  • Memory efficient for large datasets

  • No deep copy overhead

addData(data: list, loc: int | None = None)#

Add data to the state.

at(locs: Iterable[int]) → State | None#

Get the state data at a list of given locations.

is_field_data() → bool#

Check if this is field data (has entity_ids) vs point data.

toDictionary()#

Convert the State object to a dictionary.

property data: dict | list | ndarray#

Get data in backward-compatible format.

For backward compatibility, this returns dict/list format. Use data_array to get the NumPy array directly.

Returns:

  • dict: {entity_id: [values], …} for field data

  • list: [values, …] for point data

Return type:

dict or list

property data_array: ndarray#

Get data as NumPy array (high performance).

property entity_ids: ndarray | None#

Get entity IDs for field data.