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.

Parameters:

  • data (list) – Data to be added.

  • loc (int, optional) – Entity ID for field data. If None, replaces all data with point data.

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

Get the state data at a list of given locations.

Parameters:

locs (Iterable[int]) – List of node/element IDs.

Returns:

A new State object with the data at the given locations. Returns None if no data is found at the specified locations.

Note: The returned State contains a view of the data (not a copy) for performance. If you need to modify the data, make a copy.

Return type:

State or None

Notes

Callers should check for None before using the returned value:

state = my_state.at([1, 2, 3])
if state is not None:
    # use state
Performance:

  • Point data: O(1) - returns self immediately

  • Field data: O(n) where n is number of entities, using fast NumPy indexing

is_field_data() → bool#

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

Returns:

True if field data, False if point data.

Return type:

bool

toDictionary()#

Convert the State object to a dictionary.

Returns:

A dictionary representation of the State object. The ‘data’ field is converted to dict/list format for backward compatibility.

{
    'name': name,
    'data': data,  # dict for field data, list for point data
    'label': label,
    'location': location
}

Return type:

dict

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).

Returns:

Data as NumPy array. Shape: (n_entities, n_components) or (n_components,)

Return type:

np.ndarray

property entity_ids: ndarray | None#

Get entity IDs for field data.

Returns:

Entity IDs for field data, None for point data

Return type:

np.ndarray or None