idmtools.utils.filter_simulations module#

Filtering utility.

class idmtools.utils.filter_simulations.FilterItem[source]#

Bases: object

FilterItem provides a utility to filter items on a platform.

static filter_item(platform: IPlatform, item: IEntity, tags=None, status: EntityStatus | None = None, entity_type: bool = False, max_simulations: int | None = None, skip_sims=None, **kwargs)[source]#

Filter simulations from an Experiment or Suite using tag and status criteria.

By default, this filters simulations that have a status of EntityStatus.SUCCEEDED. Additional filtering can be applied by specifying tag values or tag-based conditions.

This method supports:

Skipping specific simulations by ID
Filtering based on simulation status (e.g., FAILED, SUCCEEDED)
Tag-based filtering (both exact match and conditional/lambda-based)

Examples

>>> filter_item(platform, experiment, status=EntityStatus.FAILED)
>>> filter_item(platform, experiment, tags={"Run_Number": "2"})
>>> filter_item(platform, experiment, tags={"Run_Number": lambda v: 2 <= v <= 10})
>>> filter_item(platform, experiment, tags={"Coverage": 0.8}, status=EntityStatus.SUCCEEDED)
>>> filter_item(platform, experiment, tags={"Coverage": 0.8}, max_simulations=10)

Parameters:

platform (IPlatform) – The platform instance to query simulations from.
item (IEntity) – An Experiment or Suite to filter simulations from.
tags (dict) – A dictionary of tag key-value pairs to filter by for a simulation. Values may be: * A fixed value (e.g., {“Run_Number”: 2}) * A lambda or callable function for conditional logic (e.g., {“Run_Number”: lambda v: 2 <= v <= 10})
status (EntityStatus, Optional) – The experiment’s status.
entity_type (bool, optional) – If True, return simulation entities instead of just their IDs.
skip_sims (list, optional) – A list of simulation IDs (as strings) to exclude from the results.
max_simulations (int, optional) – Maximum number of simulations to return. Returns all if not set.
**kwargs – Extra args.

Returns:

If the item is an Experiment, returns a list of simulation IDs or simulation entities (if entity_type=True).

If the item is a Suite, returns list ofdictionary where each key is an experiment ID and each value is a list of simulation IDs or simulation entities (depending on the entity_type flag).

Return type:

Union[List[Union[str, Simulation]], Dict[str, List[Union[str, Simulation]]]]

classmethod filter_item_by_id(platform: IPlatform, item_id: str, item_type: ItemType = ItemType.EXPERIMENT, tags=None, status=None, entity_type=False, skip_sims=None, max_simulations: int | None = None, **kwargs)[source]#

Retrieve and filter simulations from an Experiment or Suite by item ID.

This method looks up the specified item (Experiment or Suite) by ID on the given platform, then filters its simulations using the class’s filter_item() method.

Parameters:

platform (IPlatform) – The platform instance used to fetch the item.
item_id (str) – The unique identifier of the Experiment or Suite.
item_type (ItemType, optional) – The type of item (Experiment or Suite). Defaults to Experiment.
tags (dict, optional) – A simulation’s tags to filter by.
status (EntityStatus, Optional) – The experiment’s status.
entity_type (bool, optional) – If True, return simulation entities instead of just their IDs.
skip_sims (List[str], optional) – List of simulation IDs to skip during filtering. Defaults to an empty list.
max_simulations (int, optional) – Maximum number of simulations to return. Defaults to None (no limit).
**kwargs – Additional keyword arguments passed to filter_item().

Returns:

If the item is an Experiment, returns a list of simulation IDs or simulation entities (if entity_type=True).

If the item is a Suite, returns a dictionary where each key is an experiment ID and each value is a list of simulation IDs or simulation entities (depending on the entity_type flag).

Return type:

Union[List[Union[str, Simulation]], Dict[str, List[Union[str, Simulation]]]]

Raises:

ValueError – If the provided item_type is not Experiment or Suite.