Developer Interface

SimProv

class simprov.core.SimProv(rule_path: str, specifications_path: str, state_file_path: str = './study-state.pickle', start_api: bool = True)[source]

Represents an instance of SimProv.

Every instance has its own RuleEngine, SpecificationManager, ProvenanceGraph, and RestAPI.

During initialization the rules and specifications are automatically loaded.

Parameters:

rule_path (str) – The path where the rules are located.
specifications_path (str) – The path where the specifications are located.
state_file_path (str) – The path to the file in which the state of SimProv should be stored.

Variables:

rule_engine (RuleEngine) – The rule engine.
start_api (bool) – If true starts the REST API. Use only for testing/debugging purposes.
specification_manager (SpecificationManager) – The specification manager.
provenance_graph (ProvenanceGraph) – The provenance graph.
rest_api (RestAPI) – The REST API.
state_file_path (str) – The path to the state file.
event_log (list) – A list of all processed events.

check_dependencies_forms_cycle(dependencies: Dict) → bool[source]

Checks whether the new dependencies lead to a cycle in the provenance graph.

Parameters:: dependencies (Dict) – A Dictionary with the new dependencies.
Rtype bool:
Returns:: True if changes leads to a cycle; False otherwise

delete_study_state(study_state_file_path: str = None)[source]

Deletes the study state file if exists.

Parameters:: study_state_file_path (str, optional) – The path of the state file. If study_state_file_path is None the instance state file path is used.

get_study_state()[source]

Gets the current state of SimProv.

Returns:: The state consists of provenance graph and the event log.
Return type:: Tuple[ProvenanceGraph,List[Dict]]

load_rules_and_specifications(rule_path: str, specifications_path: str)[source]

Loads the rules and specifications.

Parameters:

rule_path (str) – The path where the rules are located.
specifications_path (str) – The path where the specifications are located.

load_study_state(study_state_file_path: str = None)[source]

Loads the study state from a state file.

Only loads the state file if the file exists.

Parameters:: study_state_file_path (str, optional) – The path of the state file. If study_state_file_path is None the state_file_path is used.

process_event(event: dict, save_study_state: bool = True)[source]

Processes an incoming event.

The process consists of the following steps:

Extracting the activity from the event using the rule engine
Normalizing and validating the activity using the specification manager
On success, the activity is chained with the provenance graph, the event is added to the event log and the REST-API emits an event signaling that the provenance graph has been updated.

Parameters:

event (dict) – The event.
save_study_state (bool) – True if the study state should be saved after processing the event

Returns:

The extracted provenance activity.

Return type:

Activity

reprocess_events_from_file(event_log_path: str)[source]

Loads events from a file and processes them.

Parameters:: event_log_path (str) – The path at which the event log is stored.

save_event_log(target_path: str)[source]

Saves the event log as JSON into a file.

Parameters:: target_path (str) – The path at which the event log should be written.

write_study_state(study_state_file_path: str = None)[source]

Writes the study state into a state file.

Parameters:: study_state_file_path (str, optional) – The path of the state file. If study_state_file_path is None the instance state_file_path is used.

Rule Engine

simprov.rule_engine.rule(event_type: str)[source]

The decorator that shall be used to mark a python function as a rule for SimProv

Parameters:: event_type (str) – The name of the event

class simprov.rule_engine.RuleEngine(rule_path: str | Path = None)[source]

Represents the rule engine that manages the rules for extracting a provenance activity from the incoming events.

Parameters:: rule_path (Union[str, Path], optional) – When provided the rules are loaded from the file.
Variables:: rule_table (Dict[str,Rule]) – A lookup table from an event type to its corresponding rule

execute_rule(event: Dict) → Activity[source]

Executes the rule that corresponds to the event type to extract the activity..

Parameters:

event (Dict) – The event.

Return type:

Activity

Returns:

The extracted activity.

Raises:

NoRuleFoundException – If no rule for the event type can be found.
InvalidRuleResultException – If the result of the rule is not an activity.

load_rules(file_path: str | Path)[source]

Loads all rules from a given file.

Parameters:: file_path (Union[str, Path]) – The file path.

register_rule(rule: Rule)[source]

Registers a new rule.

Parameters:: rule (Rule) – The rule.
Raises:: InvalidRuleSpecificationException – If a rule for the corresponding event type is already registered.

Specification Manager

class simprov.specifications.SpecificationManager(specification_path: str | Path = None)[source]

The specification manager loads and stores all entity and activity specifications.

Parameters:

specification_path (Union[str, Path], optional) – When provided the specifications are loaded from the file.

Variables:

entity_specifications (Dict[str, EntitySpecification]) – A mapping from entity names to their corresponding specifications.
activity_specifications (Dict[str, ActivitySpecification]) – A mapping from activity names to their corresponding specifications.

get_activity_specification(activity_name: str) → ActivitySpecification[source]

Returns the corresponding activity specification for an activity name.

Parameters:: activity_name (str) – The activity name.
Return type:: ActivitySpecification
Returns:: The activity specification
Raises:: ActivitySpecificationNotFoundException – If a specification can not be found.

get_agent_specification(agent_name: str) → AgentSpecification[source]

Gets the agent specification for an agent name.

Parameters:: agent_name (str) – The agent name.
Return type:: AgentSpecification
Returns:: The agent specification
Raises:: AgentSpecificationNotFoundException – If a specification can not be found.

get_entity_specification(entity_name: str) → EntitySpecification[source]

Gets the entity specification for an entity name.

Parameters:: entity_name (str) – The entity name.
Return type:: EntitySpecification
Returns:: The entity specification
Raises:: EntitySpecificationNotFoundException – If a specification can not be found.

is_editable(entity_name: str, attribute_name: str) → bool[source]

Checks whether an attribute of an entity is editable by the user.

All attributes are editable unless they are part of the primary key attributes.

Parameters:

entity_name (str) – The entity name.
attribute_name (str) – The attribute name.

Rtype bool:

Returns:

True if the attribute is editable, False otherwise

load_specification_file(file_path: str | Path)[source]

Loads the specifications from a given file.

Parameters:: file_path (Union[str, Path]) – The file path.
Raises:: InvalidSpecificationException – If an entry in the specification file is neither an entity nor an activity specification.

normalize_activity(activity: Activity)[source]

Normalizes an activity.

Iterates over all used and generated entities of activity and normalizes them.

normalize_agent(agent: Agent)[source]

Normalizes an agent.

Gets the agent specification to set all missing entity attributes to None, to set the primary key and to inject the meta information.

Parameters:: agent (Agent) – The agent.

normalize_entity(entity: Entity)[source]

Normalizes an entity.

Gets the entity specification to set all missing entity attributes to None, to set the primary key and to inject the meta information.

Parameters:: entity (Entity) – The entity.

validate_activity(activity: Activity)[source]

Validates whether the activity corresponds to its activity specification.

Parameters:: activity (Activity) – The activity.
Raises:: InvalidActivityException – If the names or count of the entity names of the activity does not match the activity specification.

validate_agent(agent: Agent)[source]

Validates whether an agent correspond to its agent specification.

Parameters:

agent (Agent) – The agent.

Raises:

PrimaryKeyAttributeNotFound – If a primary key attribute is not in included in the entity attributes
PrimaryKeyAttributeNotDefined – If the value of a primary key attribute is None

validate_entity(entity: Entity)[source]

Validates whether an entity correspond to its entity specification.

Parameters:

entity (Entity) – The entity.

Raises:

PrimaryKeyAttributeNotFound – If a primary key attribute is not in included in the entity attributes
PrimaryKeyAttributeNotDefined – If the value of a primary key attribute is None

Provenance Information

class simprov.provenance.Activity(name: str, used_entities: ~typing.List[~simprov.provenance.Entity] = <factory>, generated_entities: ~typing.List[~simprov.provenance.Entity] = <factory>, associated_agents: ~typing.List[~simprov.provenance.Agent] = <factory>, id: ~uuid.UUID = <factory>, user_generated_edges: list = <factory>)[source]

Represents a provenance activity.

Variables:

ivar (UUID) – The unique identifier of the activity.
name (str) – The name of the activity, e.g., “Specifying Simulation Model”, or “Executing Simulation Experiment”.
used_entities (List[Entity]) – A list of all entities that were used by the activity.
generated_entities (List[Entity]) – A list of all entities that were generated by the activity.

property entities: List[Entity]

Returns a list of all the entities that were used and generated by the activitiy.

Return type:: List[Entity]
Returns:: The list of all entities.

todict() → dict[source]

Returns all activity attributes as a dictionary.

It also sets the key type to be “Activity” in the resulting dictionary.

Return type:: Dict
Returns:: The node attributes.

class simprov.provenance.Entity(name: str, primary_key: ~typing.Tuple | None = None, attributes: dict = <factory>, id: ~uuid.UUID = <factory>, meta_information: dict = <factory>)[source]

Represents a provenance entity.

Variables:

ivar (UUID) – The unique identifier of the entity.
name (str) – The name of the entity, e.g., simulation model or simulation experiment.
attributes (Dict) – Holds all the attribute values of an entity, e.g., a file path and a specification.
primary_key (Tuple) – The primary key.
meta_information (Dict) – The meta information.

todict()[source]

Returns all entities attributes as a dictionary.

It also sets the key type to be “Entity” in the resulting dictionary.

Return type:: Dict
Returns:: The node attributes.

class simprov.provenance.ProvenanceGraph[source]

Represents a provenance graph.

It only consists of activities and entities. Agents are not supported right now.

Variables:

graph (DiGraph) – The graph holding all the entities and activities.
latest_entities_map (Dict[Tuple,Entity]) – A mapping from the primary keys of the entities to an entity instance.
node_map (Dict[UUID,Union[Entity,Activity]]) – A mapping from the node ids to the corresponding entities and activities.
user_generated_dependencies (Set) – A set tracking the dependencies generated by the user.

property activities: List[Activity]: A list of all activities in the provenance graph.

add_activity(activity: Activity)[source]

Adds an activity to the provenance graph.

Parameters:: activity (Activity) – The activity.

add_agent(agent: Agent)[source]

Adds an agent to the provenacne graph.

Parameters:: agent (Agent) – The entity.

add_dependency(source_node_id: UUID, target_node_id: UUID)[source]

Adds a depdency between two nodes.

Parameters:

source_node_id (UUID) – The id of the source node.
target_node_id (UUID) – The id of the target node.

add_entity(entity: Entity)[source]

Adds an entitiy to the provenacne graph.

Parameters:: entity (Entity) – The entity.

are_dependencies_are_forming_a_cycle(dependencies: Dict) → bool[source]

Checks whether the new dependencies lead to a cycle in the provenance graph.

Parameters:: dependencies (Dict) – A Dictionary with the new dependencies.
Rtype bool:
Returns:: True if changes leads to a cycle; False otherwise

chain_provenance_activity(activity: Activity)[source]

Chains an activity with the provenance graph.

It tries to replace the entities used by the activity with the “latest” version of the entities. If an entity can not be resolved it uses the original entity. Finally, the activity is added to the provenance graph.

Parameters:: activity (Activity) – The activity.

cytoscape_data() → List[Dict][source]

Returns the provenance graph for Cytoscape.

Return type:: List[Dict]
Returns:: Cytoscape-Representation of the graph.

property entities: List[Entity]: The list of all entities in the provenance graph.

is_activity(node_id: UUID) → bool[source]

Checks whether a node is an activity.

Parameters:: node_id (UUD) – The id of the node.
Return type:: bool
Returns:: True if node is an activity, False otherwise

is_agent(node_id: UUID) → bool[source]

Checks whether a node is an agent.

Parameters:: node_id (UUD) – The id of the node.
Return type:: bool
Returns:: True if node is an entity, False otherwise

is_entity(node_id: UUID) → bool[source]

Checks whether a node is an entity.

Parameters:: node_id (UUD) – The id of the node.
Return type:: bool
Returns:: True if node is an entity, False otherwise

node_data(node_id: UUID) → dict[source]

Returns the data of a node.

Parameters:: node_id (UUID) – The id of the node.
Return type:: Dict
Returns:: The node attributes.

propagate_visibility_information(node_id: UUID, hide_node: bool = False)[source]

Hides/Unhides all from a given node onwards.

Parameters:

node_id (UUID)
hide_node (bool)

remove_dependency(source_node_id: UUID, target_node_id: UUID)[source]

Removes a depdency between two nodes.

Parameters:

source_node_id (UUID) – The id of the source node.
target_node_id (UUID) – The id of the target node.

update_activity_dependencies(activity_id: UUID, changes: Dict)[source]

Updates the dependencies of an activity.

Parameters:

activity_id (UUID) – The id of the activity.
changes (Dict) – A dictionary of the changes.

update_entity_attributes(entity_id: UUID, changes: Dict)[source]

Updates the attributes of an entity.

Parameters:

entity_id (UUID) – The id of the entity.
changes (Dict) – A dictionary of attribute-value mapping.

Rules and Specifications

class simprov.rule_engine.Rule(event_type: str, func: Callable)[source]

Represents a rule that is used for extracting an activity from an event.

Variables:

event_type (str) – The name of the event for which the rule should be executed.
func (Callable) – The function that extracts the activity.

class simprov.specifications.EntitySpecification(name: str, required_attributes: list = <factory>, attributes: list = <factory>, primary_key_attributes: list = <factory>, style_info: dict = <factory>)[source]

Represents a specification of an entity.

Variables:

name (str) – The name of the entity for whic°h the specification should be used, e.g., simulation model or simulation experiement.
required_attributes (List[str]) – A list of attributes names that are required for an entiy
primary_key_attributes (List[str]) – A list of attributes that form the primary key of an entity.
attributes (List[str]) – A list of all attribute names of an entity. It also contains the required attributes as well as the primary key attributes.
style_info (Dict) – Holds the style information extracted from the specification file. It can be used to store information about how an entity should be rendered in the webview.

class simprov.specifications.ActivitySpecification(name: str, used_entities: ~typing.Dict[str, ~simprov.specifications.OccurenceModifier] = <factory>, generated_entities: ~typing.Dict[str, ~simprov.specifications.OccurenceModifier] = <factory>, associated_agents: ~typing.Dict[str, ~simprov.specifications.OccurenceModifier] = <factory>)[source]

Represents a specification of an activity.

Variables:

name (str) – The name of the activity for which the specification should be used.
used_entities (Dict[str,OccurenceModifier]) – A mapping from the entity names of entities that were used by the activity to a modifier.
generated_entities (Dict[str, OccurenceModifier]) – A mapping from the entity names of entities that were generated by the activity to a modifier.

class simprov.specifications.OccurenceModifier(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Represents a modifier that signals how often an entity of a name can be used or generated by an activity.

Possible Values:

SINGLE - An entity has occur exactly once
ZERO_OR_ONE - An entity is optional
ONE_OR_MORE - An entity can occur arbitrary often
ZERO_OR_MORE - An entity has to occur at least once

Exceptions

exception simprov.exceptions.ActivityAlreadyDefinedException[source]: The activity is already defined.

exception simprov.exceptions.ActivitySpecificationNotFoundException[source]: The activity specification can not be found.

exception simprov.exceptions.AgentSpecificationNotFoundException[source]: The agent specification can not be found.

exception simprov.exceptions.EntityAlreadyDefinedException[source]: The entity is already defined.

exception simprov.exceptions.EntitySpecificationNotFoundException[source]: The entity specification can not be found.

exception simprov.exceptions.InvalidActivityException[source]: The activity is invalid.

exception simprov.exceptions.InvalidActivitySpecificationException[source]: The activity specification is invalid.

exception simprov.exceptions.InvalidEntitySpecificationException[source]: The entity specification is invalid.

exception simprov.exceptions.InvalidRuleResultException[source]: The rule do not return an activity.

exception simprov.exceptions.InvalidRuleSpecificationException[source]: The rule specification is invalid.

exception simprov.exceptions.InvalidSpecificationException[source]: The specification is neither an entity nor an activity specification.

exception simprov.exceptions.NoRuleFoundException[source]: The rule for the event type can not be found.

exception simprov.exceptions.PrimaryKeyAttributeNotDefinedException[source]: The primary key attribute has no value.