autotwin_pmswsgi 1.0.2

Process Mining Service WSGI for Auto-Twin

Processing Mining Service (PMS) WSGI for Auto-Twin

The processing mining service (PMS) WSGI implements a RESTful API that invokes different system discovery modules to automatically create, update and delete graph models, Petri nets and automata in a system knowledge graph (SKG). Besides, the RESTful API enables the execution of a battery model for estimating the state of charge (SoC) across a time period.

Installation

To facilitate installation, the PMS WSGI is released as a Python module, autotwin_pmswsgi, in the PyPI repository. autotwin_pmswsgi implicitly depends on pygraphviz. This dependency however cannot be resolved automatically by pip. As a preparation, you need to install pygraphviz manually, following instructions provided here. Whenever pygraphviz is available, the latest version of autotwin_pmswsgi can be easily installed with pip.

pip install autotwin_pmswsgi

Deployment

The PMS WSGI is almost ready to be deployed for production use once autotwin_pmswsgi is installed successfully. Four environment variables are additionally required to specify the Neo4j instance that holds the SKG of the system under consideration.

Name	Description
NEO4J_URI	URI of the Neo4j instance, e.g. neo4j://localhost:7687
NEO4J_USERNAME	Username for the Neo4j instance, e.g. neo4j
NEO4J_PASSWORD	Password for the Neo4j instance, e.g. 12345678
NEO4J_DATABASE	Database where the SKG is stored, e.g. neo4j

After setting the above environment variables, you can start up the PMS WSGI on a Waitress server by executing

waitress-serve autotwin_pmswsgi:wsgi

Containerization

To enable containerization, the PMS WSGI is also released as a Docker image, ghcr.io/autotwineu/proc-mining-serv, in the GHCR registry. Suppose that a Docker engine is running on your machine. Deploying the PMS WSGI on a Docker container named proc-mining-serv can be done via a single command.

Windows:

docker run --detach ^
--env NEO4J_URI=<NEO4J_URI> ^
--env NEO4J_USERNAME=<NEO4J_USERNAME> ^
--env NEO4J_PASSWORD=<NEO4J_PASSWORD> ^
--env NEO4J_DATABASE=<NEO4J_DATABASE> ^
--volume <CLUSTERING_DIRECTORY>:/proc-mining-serv/clusterings ^
--volume <BATTERY_MODEL_DIRECTORY>:/proc-mining-serv/battery-models ^
--name proc-mining-serv ^
--pull always ghcr.io/autotwineu/proc-mining-serv

Linux:

docker run --detach \
--env NEO4J_URI=<NEO4J_URI> \
--env NEO4J_USERNAME=<NEO4J_USERNAME> \
--env NEO4J_PASSWORD=<NEO4J_PASSWORD> \
--env NEO4J_DATABASE=<NEO4J_DATABASE> \
--volume <CLUSTERING_DIRECTORY>:/proc-mining-serv/clusterings \
--volume <BATTERY_MODEL_DIRECTORY>:/proc-mining-serv/battery-models \
--name proc-mining-serv \
--pull always ghcr.io/autotwineu/proc-mining-serv

<NEO4J_URI>, <NEO4J_USERNAME>, <NEO4J_PASSWORD> and <NEO4J_DATABASE> correspond to the values of the four environment variables required by the PMS WSGI (see Deployment). <CLUSTERING_DIRECTORY> and <BATTERY_MODEL_DIRECTORY> are host directories where clustering and battery model files are located.

RESTful API

The PMS WSGI listens HTTP requests on port 8080 and is accessible through a RESTful API that exposes the following endpoints for different types of models. The content types of the request and response for each API endpoint are either application/json or application/octet-stream.

---

API Endpoints for Graph Models

POST /graph-model (create a graph model in the SKG)

Parameters

None

Body

Content: application/json

Key	Type	Default	Description
name	string	"System"	Name of the system to be discovered
version	string	""	Version of the system to be discovered
data:clustering:path	string	""*	Name of the clustering file to be used
data:clustering:default	string	""†	Cluster of parts absent from the clustering file
data:filters:interval	array[number|string]	[0.0, 0.0]	Interval during which events are selected
data:filters:station	array[string]	[]‡	Set of stations at which events are selected
data:filters:family	array[string]	[]‡	Set of families for which events are selected
data:filters:type	array[string]	[]‡	Set of types for which events are selected
data:usage	number	0.5	Minimum data usage to be ensured
model:time_unit	string	"s"	Unified time unit of algorithm and model parameters
model:operation:io_ratio	number	1.5	Minimum ratio of input to output for an ATTACH/COMPOSE operation
model:operation:co_ratio	number	0.5	Minimum ratio of cross to output for an ATTACH/ORDINARY operation
model:operation:oi_ratio	number	1.5	Minimum ratio of output to input for a DETACH/DECOMPOSE operation
model:operation:ci_ratio	number	0.5	Minimum ratio of cross to input for a DETACH/ORDINARY operation
model:formula:ratio	number	0.0	Minimum ratio of a formula to the primary one
model:delays:seize	number	0.0	Maximum delay in seizing a queued part
model:delays:release	number	0.0	Maximum delay in releasing a blocked part
model:cdf:replace_pts	boolean	false	Replace or drop invalid samples in a processing time CDF
model:cdf:replace_tts	boolean	false	Replace or drop invalid samples in a transfer time CDF
model:cdf:points	number	100	Maximum number of points in a CDF

^{* An empty string disables the import of clustering information. ↩
† An empty string ignores parts not belonging to any clusters. ↩
‡ An empty array refers to the universe of stations/families/types. ↩}

Example:

{
    "name": "Pizza Line",
    "version": "V4",
    "data": {
        "filters": {
            "interval": [
                0,
                500000000
            ],
            "station": [],
            "family": [],
            "type": []
        },
        "usage": 0.5
    },
    "model": {
        "time_unit": "ms",
        "operation": {
            "io_ratio": 1.5,
            "co_ratio": 0.5,
            "oi_ratio": 1.5,
            "ci_ratio": 0.5
        },
        "formula": {
            "ratio": 0.06
        },
        "delays": {
            "seize": 30000,
            "release": 0
        },
        "cdf": {
            "replace_pts": false,
            "replace_tts": false,
            "points": 100
        }
    }
}

Response

Code: 201

Content: application/json

Key	Type	Description
model_id	string	ID of the generated graph model

Example:

{
    "model_id": "4:31f61bae-dad6-4cda-bb63-d4700847dea5:620887"
}

---

API Endpoints for Petri Nets

POST /petri-net (create a Petri net in the SKG)

Parameters

None

Body

Content: application/json

Key	Type	Default	Description
name	string	"System"	Name of the system to be discovered
version	string	""	Version of the system to be discovered
data:filters:interval	array[number|string]	[0.0, 0.0]	Interval during which events are selected
data:filters:station	array[string]	[]*	Set of stations at which events are selected
data:filters:family	array[string]	[]*	Set of families for which events are selected
data:filters:type	array[string]	[]*	Set of types for which events are selected
data:usage	number	0.5	Minimum data usage to be ensured
model:operation:io_ratio	number	1.5	Minimum ratio of input to output for an ATTACH/COMPOSE operation
model:operation:co_ratio	number	0.5	Minimum ratio of cross to output for an ATTACH/ORDINARY operation
model:operation:oi_ratio	number	1.5	Minimum ratio of output to input for a DETACH/DECOMPOSE operation
model:operation:ci_ratio	number	0.5	Minimum ratio of cross to input for a DETACH/ORDINARY operation
model:formula:ratio	number	0.0	Minimum ratio of a formula to the primary one

^{* An empty array refers to the universe of stations/families/types. ↩}

Example:

{
    "name": "Pizza Line",
    "version": "V4",
    "data": {
        "filters": {
            "interval": [
                0,
                500000000
            ],
            "station": [],
            "family": [],
            "type": []
        },
        "usage": 0.5
    },
    "model": {
        "operation": {
            "io_ratio": 1.5,
            "co_ratio": 0.5,
            "oi_ratio": 1.5,
            "ci_ratio": 0.5
        },
        "formula": {
            "ratio": 0.06
        }
    }
}

Response

Code: 201

Content: application/json

Key	Type	Description
model_id	string	ID of the generated Petri net

Example:

{
    "model_id": "4:31f61bae-dad6-4cda-bb63-d4700847dea5:620887"
}

---

API Endpoints for Automata

POST /automaton (create an automaton in the SKG)

Parameters

None

Body

Content: application/json

Key	Type	Default	Description
name	string	"System"	Name of the system to be discovered
version	string	""	Version of the system to be discovered
data:filters:interval	array[number|string]	[0.0, 0.0]	Interval during which events are selected
model:pov	string	"item"	Point of view to be focused on

Example:

{
    "name": "Pizza Line",
    "version": "V4",
    "data": {
        "filters": {
            "interval": [
                0,
                500000000
            ]
        }
    },
    "model": {
        "pov": "item"
    }
}

Response

Code: 201

Content: application/json

Key	Type	Description
model_id	string	ID of the generated automaton

Example:

{
    "model_id": "4:31f61bae-dad6-4cda-bb63-d4700847dea5:620887"
}

---

API Endpoints for Battery Models

GET /api/v1/projects/ids (get the project IDs of battery models)

Parameters

None

Body

None

Response

Code: 200

Content: application/json

Key	Type	Description
i:projectUUID	string	Project ID of the i-th battery model
i:scenarioUUID	string	Scenario ID of the i-th battery model

Example:

[
    {
        "projectUUID": "31f61bae-dad6-4cda-bb63-d4700847dea5",
        "scenarioUUID": "31f61bae-dad6-4cda-bb63-d4700847dea5"
    }
]

GET /api/v1/scenario-executions/ids (get the execution IDs of battery models)

Parameters

None

Body

None

Response

Code: 200

Content: application/json

Key	Type	Description
i:uuid	string	Execution ID of the i-th battery model

Example:

[
    {
        "uuid": "31f61bae-dad6-4cda-bb63-d4700847dea5"
    }
]

GET /api/v1/scenario-executions/{execution_id}/parameters (get the parameters of a battery model)

Parameters

Name	Type	Description
execution_id	string	Execution ID of the battery model

Body

None

Response

Code: 200

Content: application/json

Key	Type	Description
i	object	i-th parameter of the battery model

Example:

[]

GET /api/v1/scenario-executions/{execution_id}/json (get SoC estimation by a battery model)

Parameters

Name	Type	Description
execution_id	string	Execution ID of the battery model

Body

Content: application/json

Key	Type	Default	Description
interval	array[number]	[0, 0]	Interval during which SoC is estimated

Example:

{
    "interval": [
        1730419200000,
        1732924800000
    ]
}

Response

Code: 200

Content: application/json

Key	Type	Description
component	string	ID of the current component
data:i:name	string	Name of the i-th data entry
data:i:description	string	Description of the i-th data entry
data:i:type	string	Type of the i-th data entry
data:i:payload	string	Payload of the i-th data entry

Example:

{
    "component": "C12",
    "data": [
        {
            "name": "Battery DT SoC",
            "description": "Battery DT SoC results",
            "type": "chart",
            "payload": "[{\"time\": 1730419200000, \"value\": 50.0}]"
        }
    ]
}

GET /api/v1/scenario-executions/{execution_id}/out (get SoC estimation by a battery model)

Parameters

Name	Type	Description
execution_id	string	Execution ID of the battery model

Body

Content: application/json

Key	Type	Default	Description
interval	array[number]	[0, 0]	Interval during which SoC is estimated

Example:

{
    "interval": [
        1730419200000,
        1732924800000
    ]
}

Response

Code: 200

Content: application/octet-stream, attachment; filename=out.zip

---