Specifying Rules

The rules within this software are specified as Python functions (see Example). These functions play a crucial role in processing events within SimProv. To maintain clarity and distinguish rule functions from other functions, such as auxiliary functions for file manipulation, we enforce the use of the @rule decorator on every rule function.

Each rule function must be annotated with the @rule decorator, ensuring clarity in function identification. Additionally, the event type for which the rule function is intended must be passed as an argument to this decorator.

During the loading of rules, the SimProv evaluates these decorators, creating an internal mapping in the rule engine between event types and their corresponding rule functions. This mapping facilitates execution of the rule function associated with the type attribute of incoming events. Events lacking a defined rule function are rejected and recorded in the error log for further analysis.

Rule functions are structured as unary functions, accepting an event dictionary as input and returning a provenance activity represented by an Activity object. Within these functions, entities, each belonging to the Entity class, must be instantiated and configured using event information. These entities are then designated as either used or generated by the activity. Optionally, agents, objects of the Agent class, can also be associated with the activity for further contextualization.

from pathlib import Path
from simprov import Activity, Entity, rule

# Auxilary function extracting the file name from a file path
def file_name_from(path):
        return Path(path).name

# Rule function for events of type "Experiment Executed"
@rule("Experiment Executed")
def process_experiment_executed_event(event:dict)-> Activity:
        activity = Activity("Executing Experiment")

        experiment = Entity("Experiment")
        experiment_path = event["executed_experiment"]
        experiment["File Path"] = experiment_path
        experiment["Name"] = file_name_from(experiment_path)
        experiment["Specification"] = event["experiment_specification"]

        model = Entity("Simulation Model")
        model_path = event["with_model"]
        model["File Path"] = model_path
        model["Name"] = file_name_from(model_path)
        model["Specification"] = event["model_specification"]

        data = Entity("Data")
        data_path = event["generated_data"]
        data["File Path"] = data_path
        data["Name"] = file_name_from(data_path)
        data["Content"] = event["data_content"]

        tel = Agent("Tellurium")
        tel["Version"] = event["tellurium_version"]


        activity.entities_used = [model, experiment]
        activity.entities_generated = [data]
        activity.agents_associated = [tel]

        return activity