4.1.1.9.1.5. pyfem.util.itemList module

class itemList

Bases: dict

A dictionary-based container that maintains items with both global IDs and continuous local indices.

This class extends the built-in dict to provide a mapping from global identifiers (IDs) to items, and also provides methods to query items by their position in the dictionary. It is commonly used in finite element analysis to manage collections of elements, nodes, or other entities that require both global and local numbering.

Items are stored with integer IDs as keys and arbitrary values as items.

Examples

Create and populate an itemList: >>> items = itemList() >>> items.add(1, “element_1”) >>> items.add(5, “element_5”) >>> items.get(1) ‘element_1’ >>> items.findID(0) 1

Raises:

RuntimeError – If attempting to add an item with a duplicate ID, or if invalid arguments are provided to methods.

add(ID: int, item: Any) → None

Add an item with an associated ID to the list.

If the ID already exists in the itemList, a RuntimeError is raised to prevent accidental overwriting of existing items.

Parameters:

• ID (int) – The unique global identifier for the item. Must be unique within this itemList.

• item (Any) – The value or object to store. Can be any type (int, str, object instance, etc.).

Raises:

RuntimeError – If the ID already exists in the itemList.

Examples

>>> items = itemList()
>>> items.add(10, "data")
>>> items.add(10, "other")  
Traceback (most recent call last):
    ...
RuntimeError: ID 10 already exists in itemList

get(IDs: int | list) → Any

Retrieve item(s) from the list by ID or list of IDs.

Parameters:

IDs (int | list[int]) – A single ID (returns one item) or a list of IDs (returns a list of items).

Returns:

If IDs is an int, returns the single item. If IDs is a list,

returns a list of items corresponding to the requested IDs.

Return type:

Any

Raises:

• RuntimeError – If IDs is neither an int nor a list.

• KeyError – If a requested ID does not exist in the itemList.

Examples

>>> items = itemList()
>>> items.add(1, "first")
>>> items.add(2, "second")
>>> items.get(1)
'first'
>>> items.get([1, 2])
['first', 'second']

getIndices(IDs: list | int = -1) → list | int

Get the local index/indices corresponding to one or more global IDs.

Returns the position(s) of items in the dictionary’s key sequence. Useful for converting between global IDs and continuous local numbering (0, 1, 2, …).

Parameters:

IDs (int | list[int], optional) – A single ID, list of IDs, or -1 to retrieve all indices. Defaults to -1 (all indices).

Returns:

If IDs is -1, returns list of all keys. If IDs is an int,

returns the index (int) of that ID. If IDs is a list, returns a list of indices for those IDs.

Return type:

list[int]

Raises:

• RuntimeError – If IDs is not of type int, list, or -1.

• ValueError – If a requested ID does not exist.

Examples

>>> items = itemList()
>>> items.add(100, "first")
>>> items.add(200, "second")
>>> items.getIndices()
[100, 200]
>>> items.getIndices(100)
0
>>> items.getIndices([100, 200])
[0, 1]

findID(index: int) → int

Retrieve the global ID of an item at a given local index.

This is the inverse operation of getIndices() for a single index, converting from continuous local numbering (0, 1, 2, …) back to global IDs.

Parameters:

index (int) – The local index (position) of the item in the ordered sequence of items.

Returns:

The global ID of the item at the specified index.

Return type:

int

Raises:

IndexError – If the index is out of range.

Examples

>>> items = itemList()
>>> items.add(10, "first")
>>> items.add(20, "second")
>>> items.findID(0)
10
>>> items.findID(1)
20