Package: prosimos
ProsimosProsimos is a Business Process Simulation Engine that supports differentiated resources.
Prosimos considers resource pools formed by a set of resources (process participants) with different profiles.
For example, each resource has individual calendars, costs, and a differentiated performance to execute the process activities.
Besides, pools can share resources, i.e., a resource may play different roles in the organization, thus performing several tasks.RequirementsPython 3.9+Poetry 1.4.2For dependencies, please, checkpyproject.tomlGetting Startedgit clone https://github.com/AutomatedProcessImprovement/Prosimos.gitSet up Python environment using Poetry tool:poetry installOnce all the dependencies all installed, open a terminal and from the root folder run the following comand (i.e., all in one line):poetry run prosimos start-simulation --bpmn_path <Path to the BPMN file with the process model> 
                                     --json_path <Path to the JSON file with the differentiated simulation parameters>
                                     --total_cases <Number of process instances to simulate>
                                     --log_out_path <(Optional) Path to the CSV file to save the statistics/metrics after running the simulations>
                                     --stat_out_path <(Optional) Path to the CSV file to save the event-log of the simulation>
                                     --starting_at <(Optional) Date-time of the first process case in the simulation as a string. For example, 2022-06-21T13:22:30.035185+03:00>The last three parameters are optional.
If none of the output file pathsstat_out_pathandlog_out_pathare provided, thenstat_out_pathis used by default, and the statistics file generated in the current directory.
If parameterstarting_atis not provided, the current date-time is assigned as starting point for the simulation.Simulation Input File FormatsThe first input parameter described by--bpmn_pathis a process model written in the Business Process Model and Notation
(BPMN Standard).
Note thatProsimosonly extracts the information related to the control-flow from the BPMN model,
i.e., the tasks, gateways, and their relations from the flow-arcs.
The information associated with the remaining simulation parameters,
e.g., arrival time distributions, resource tasks associations, calendars, branching probabilities and task duration distributions,
are specified separately in a JSON file.The JSON file with the simulation parameters is split into 6 sections described below.
Note that the order of the sections is not relevant, i.e., they can appear in any order in the JSON file."resource_profiles": Contains the information of the resources, grouped into pools.
Specifically, it includes a set of resource pools. Each resource pool is represented by its ID,
containing a name and a "resource_list". Besides, each resource in "resource_list" contains id, name,
cost per hour, and the amount."arrival_time_calendar": List of time intervals in which new process cases can be started on a weekly calendar basis.
Each calendar interval is described starting from weekday (Monday, ..., Sunday) at some beginTime,
until another (not necessarily different) weekday to some endTime."arrival_time_distribution": Probability distribution function that describes how a new process case is started
across the arrival calendar.Prosimosallows any of the functions supported by the Python libraryScipy Stats. Specifically,
the distribution function is represented by its name and a list of parameters
(i.e., typically ranging from 1 to 3 floating numbers depending on the function).
For the complete list of available distributions, please check theScipy Stats documentation. The unit of measurement of values provided asdistribution_paramsis seconds."gateway_branching_probabilities": Represents the probability for the process execution to move towards any outgoing
flow of each split (inclusive or exclusive) gateway in the process model. So, for each gateway, the set of pairs
outgoing_flow -> probability (between 0 and 1) is represented. Note that the sum of all the probabilities for a
given gateway must always be 1."task_resource_distribution": Maps each task in the process model and the list of resources that can perform it.
For each task, represented by its ID, the list of allowed resources and a probability distribution function
(per resource) that describes its duration are represented. Note that the distribution function of a task may vary
per resource. As for the arrival time distributions,Prosimosallows any of the functions supported by the Python
libraryScipy Stats. The unit of measurement of values provided asdistribution_paramsis seconds."resource_calendars": List of time intervals in which a resource is available to perform a task on a weekly calendar basis.
Each calendar interval is described starting from weekday (Monday, ..., Sunday) at some beginTime,
until another (not necessarily different) weekday to some endTime."batch_processing": List of tasks that are batched (= could be executed together based on the specified rules).type. There might be batched tasks of two types:SequentialorParallel.size_distribdefines the probability of tasks to be executed in batches of the specified size. The total sum of values should be 1 (which equals 100% of tasks). For example, if we want to imply that all tasks are being batched, we say:"size_distrib": [
      {
          "key": "1",
          "value": 0
      },
      {
          "key": "2",
          "value": 1
      }
  ]duration_distribdefines the scaling factor for the activity's duration based on the number of tasks in the batch. Let's say one defines the array in the following way:"duration_distrib": [
      {
          "key": "3",
          "value": 0.8
      }
  ]This means that batches with 1 or 2 tasks inside will be executed with the defined (original) duration. Starting from batches with 3 tasks inside, the duration of the individual task inside the batch will be scaled by0.8. The array should contain objects with unique keys. The tool will sort values internally, so the user does not need to provide them in ascending order.firing_rules."case_attributes": Description on which case attributes should be generated during the simulation and what value it should have. There is a possibility to introduce two types of case attributes:discreteandcontinuous. Thevaluesproperty of thecontinuouscase attribute is defined as a distribution function selected from the Python libraryScipy Stats. The unit of measurement of values provided asdistribution_paramsis seconds. Thevaluesproperty of thediscretecase attribute is defined as an array of possible choices with theirs probability accordingly. The sum of probabilities should be equal to 1.An example of the general structure of the input JSON parameters with the simulation parameters could be foundhere.Running Experiments BPM-2022git clone https://github.com/AutomatedProcessImprovement/Prosimos.gitSet up Python environment using the built-in venv module from requirements.txt.Unzip the file input_output_files.zip, to add the folderinput_output_filescontaining all the input files used in
the experimentation (excluding the log insurance which is private) in the root folder.Once all the dependencies all installed, run the scriptbpm22_experiments_script.py, in the foldertesting_scripts.
Then check the information printed in the terminal.Running tests and receive a coverage reportpytest --cov-config=.coveragerc --cov --cov-report=html --cov-branchIf one wants to skip running the tests and just overview a coverage report, one needs to unziphtmlcov.ziparchive. Unpacked folderhtmlcovcontains HTML coverage report, in general and per each file.Notes on releasing a new versionOnce you are done with the development and all changes are inmasterbranch, we can move forward with releasing PyPI package. The workflow grabs the package version frompyproject.toml. So before proceeding further, make sure that you updated a version of the package to-be-released inpyproject.tomlfile. Next, take the following steps to release the new version:Build & Testjob succeeded on themasterbranch. This means all tests are passing. (The job is triggered automatically when you push new changes tomaster)Go toActionstab.FindRelease PyPI packagefrom the list of all existing actions on the left-side menu.Start the workflow by clicking onRun workflowbutton.After the task success, double verify that the new version was published on PyPI (https://pypi.org/project/prosimos/).Development notesUse local version ofpix-frameworkIn case you want to introduce and test changes both topix-frameworkandProsimos, we need to install local version ofpix-frameworkinstead of the PyPI released version. For this, the following command needs to be run:poetry add --editable <relative-path>, where<relative-path>should be changed with the path to the root folder ofpix-framework(e.g., .../pix-framework).