Introduction
Intended audience
System integrators who want to develop solutions based on the modeling of industrial continuous processes with the LIBPF™ enabling technology.
Scope
Give a step-by-step tutorial and a reference for the usage of the Pasteurization models through the RESTful Model User API.
Prerequisites
Basic knowledge of the Pasteurization model and process (see references).
Basic knowledge of shell terminal commands or other tools suitable to run GET / POST / PUT / DELETE commands through HTTP protocol.
RESTful API access
The RESTful API can be basically accessed with any Internet browser by typing the addresses as usual URLs in the browser address field; but browsers only support the HTTP "GET" request - whenever a POST, PUT or DELETE verb must be used, it is best to use a more flexible tool. The sample commands use the cURL utility, a command-line tool for transferring data using various protocols. Use your preferred tools, there are several browser extensions (HttpRequester, REST easy ...) and windows graphical tools (fiddler2, wfetch) you can use.
The sample commands use the http://simevo.com/api/process/pasteurize/ URL as service (that's the location of the publicly accessible demo service); please replace this URL with the name of your actual service.
Model life cycle
To get a list of all available types run:
curl -k -X GET http://simevo.com/api/process/pasteurize/types
Or add a destination of the output to actually save it as a text file:
curl -k -X GET http://simevo.com/api/process/pasteurize/types > types.json
You can also try it in your browser accessing the URL http://simevo.com/api/process/pasteurize/types.
This outputs a long list of types and their capabilities. Using "find" functions it is easier to find a specific type with its name and description
An extract of the expected response could be:
{
"service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef",
"types": [
...
{
"category": "flowsheet",
"integerOptions": [],
"instantiable": true,
"name": "Pasteur",
"description": "Generic continuous pasteurization process",
"stringOptions": [
{
"enumerator": "processType",
"name": "processType",
"value": "HTST15",
"description": "adjusts temperature and holding time"
},
{
"enumerator": "feedType",
"name": "feedType",
"value": "chocolateIceCream",
"description": "sets a predefined composition for the fluid to be processed"
}
],
"icon": "Pasteur.svg"
}
]
}
Creation
Create a new case with default settings
curl -k -X -d '' POST http://simevo.com/api/process/pasteurize/cases
Expected response:
{
"modified_at": 1427880901.18888,
"case_uuid": "80a73b75-17d2-4bb7-bb69-1c68930b880e",
"description": "",
"url": "http://simevo.com/api/process/pasteurize/cases/80a73b75-17d2-4bb7-bb69-1c68930b880e",
"service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef",
"created_at": 1427880901,
"tag": "",
"type": "Pasteur"
}
Create a new case with specified type, tag, description and options
curl -k -X POST -d '{"type":"Pasteur",
"tag":"case123",
"description":"case with 1 2 3 times",
"stringOptions": {
"processType":"HTST15",
"feedType":"chocolateIceCream"
} }' http://simevo.com/api/process/pasteurize/cases
Or, if the '{ ... }' string is packed as a json file (case_descriptor.json):
cat > case_descriptor.json
{
"type":"Pasteur",
"tag":"case123",
"description":"case with 1 2 3 times",
"stringOptions": {
"processType":"HTST15",
"feedType":"chocolateIceCream"
}
}
^d
curl -k -X POST -d @case_descriptor.json http://simevo.com/api/process/pasteurize/cases
or:
cat case_descriptor.json | curl -k -X POST -d - http://simevo.com/api/process/pasteurize/cases
For the supported types, and option values, interpret the output of the types command above as detailed in the "Instantiating and using a Model" chapter of the LIBPF™ Model User API documentation.
Expected response:
{
"modified_at": 1427880852.19795,
"case_uuid": "25c92f85-74b2-4022-9ec0-fbbeb6266ac4",
"description": "case with 1 2 3 times",
"url": "http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4",
"service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef",
"created_at": 1427880852,
"tag": "case123",
"type": "Pasteur"
}
Pay attention to the response which contain an "url" string associated to the case handle (i.e. "/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4" : the handle is 25c92f85-74b2-4022-9ec0-fbbeb6266ac4). You should annotate that value for further model accesses.
Database purge
To delete (purge) all database saved cases run:
curl -k -X DELETE http://simevo.com/api/process/pasteurize/cases
Expected response:
{"service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef"}
Deletion
To delete a specific saved case run:
curl -k -X DELETE http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4
replace the code 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.
Model usage
Remark: All variable inside the model are input, calculated and returned using the SI of units of measurement.
Set variables and calculate
To set one or more input variables and immediately re-calculate the model, POST on the case handle, with a JSON-encoded array of variable/values in the request:
curl -k -X POST -d '{
"controlled": [ {
"variable": "coolT",
"end": 274.15
}] }' http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4
replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.
Or, if the '{ ... }' string is packed as a json file (changes.json):
cat > changes.json
{ "controlled": [
{
"variable": "coolT",
"end": 274.15
} ] }
^d
curl -k -X POST -d @changes.json http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4
replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.
Or:
cat changes.json | curl -k -X POST -d - http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4
Expected response:
{"message": "success", "error": 0}
Remark: the variable setting actually call the model re-calculation, so it is best to set multiple variables at once to avoid multiple re-calculation:
curl -k -X POST -d '{ "controlled":
[{ "variable": "S01.T", "end": 300 },
{ "variable": "RX:reactions[0].z", "end": 0.95 }
] }' http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4
Calculate
To force the model calculation without setting any variable, POST the on the case handle, without empty data in the request:
curl -k -X POST -d '' http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4
replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.
Expected response:
{
"modified_at": 1427881237.10185,
"case_uuid": "25c92f85-74b2-4022-9ec0-fbbeb6266ac4",
"description": "",
"url": "http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4",
"service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef",
"created_at": 1427881236.0,
"tag": "",
"type": "Pasteur"
}
Get results
Each input / output variable is individually accessible with a GET request:
curl -k -X GET http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/quantities/coolT
replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.
You can also try it in your browser accessing the URL http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/quantities/coolT.
Expected response:
{
"service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef",
"value": 278.15,
"path": "coolT"
}
It is possible to dump the whole model in a txt format:
curl -k -X GET http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/txt
replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.
Or add a destination of the output to actually save it as a text file:
curl -k -X GET http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/txt > myOutputFile.txt
You can also try it in your browser accessing the URL http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/txt.
Model tools
Homotopy
Not yet supported through RESTful API
curl -k -X POST -d '{ "controlled": [
{
"variable": "S01.T",
"start": 200 ,
"end": 300
}, {
"variable": "RX:reactions[0].z",
"start": 0.27 ,
"end": 0.95
} ] }' http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/homotopy
replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.
Or, if the '{ ... }' string is packed as a json file (changes.json):
cat > changes.json
{ "controlled": [
{
"variable": "S01.T",
"start": 200 ,
"end": 300
}, {
"variable": "RX:reactions[0].z",
"start": 0.27 ,
"end": 0.95
} ] }
^d
curl -k -X POST -d @changes.json http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/homotopy
Or:
cat changes.json | curl -k -X POST -d - http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/homotopy
Sensitivity
Not yet supported through RESTful API
curl -k -X GET -d '{
"controlled": [
{
"variable": "S01.T",
"start": 200,
"end": 300
},
{
"variable": "RX:reactions[0].z",
"start": 0.27,
"end": 0.95
}
],
"monitored": [
{ "variable": "S01.P" },
{ "variable": "RX.duty" }
] }' http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/sensitivity
replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.
Or, if the '{ ... }' string is packed as a json file (sensitivity.json):
cat > sensitivity.json
{
"controlled": [
{
"variable": "S01.T",
"start": 200,
"end": 300
},
{
"variable": "RX:reactions[0].z",
"start": 0.27,
"end": 0.95
}
],
"monitored": [
{ "variable": "S01.P" },
{ "variable": "RX.duty" }
]
}
^d
curl -k -X POST -d @sensitivity.json http://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/sensitivity
Or:
cat sensitivity.json | curl -k -X POST -d - /cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/sensitivity
Pasteurization Model references
-
Detailed process model description for the Pasteurization demo
-
Model Developer step-by-step tutorial for the creation of the Pasteurization example