Run an execution with advanced options
You can tweak engine execution by specifying other parameters in the request body of the POST/api/compute/execution endpoint.
Engine version¶
By default, the latest version of engine is executed. You can change it by specifying version:
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD",
"version": "2019.1"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
Click to show example shell script to run an engine execution with specific engine version
projectId="<replacewithprojectid>" openapikey="<replacewithopenapikey>" # create execution curl -L -X POST "https://api.mike-cloud-test.com/api/compute/execution" \ -H 'api-version: 2' \ -H 'dhi-service-id: engine' \ -H "dhi-project-id: $projectId" \ -H "dhi-open-api-key: $openapikey" \ -H 'Content-Type: application/json' \ --data-raw '{ "inputs": [ { "uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm", "engine": "FemEngineHD", "version": "2019.1" }, { "uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh" } ], "options": { "poolType": "VM-S-5", "nodeCount": 1 } }'
The list of versions is available in the response of /engine/list endpoint, see Getting available engines for details.
Scenario name¶
A short description can be associated with an engine execution by using the optional scenarioName parameter.
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD",
"localPath": "data/"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
},
"scenarioName": "Determine the wind set-up in a lake"
}
The scenarioName is shown as part of the details of an existing execution in the responses of GET/api/compute/execution/{id}, GET/api/compute/execution/list and GET/api/compute/execution/my-list endpoints, see Get execution details for details.
Folder options¶
Setting up the folders where the input files are located is done by using the localPath option:
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD",
"localPath": "data/"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
Click to show example shell script to run an engine execution with folder options
projectId="<replacewithprojectid>" openapikey="<replacewithopenapikey>" # create execution curl -L -X POST "https://api.mike-cloud-test.com/api/compute/execution" \ -H 'api-version: 2' \ -H 'dhi-service-id: engine' \ -H "dhi-project-id: $projectId" \ -H "dhi-open-api-key: $openapikey" \ -H 'Content-Type: application/json' \ --data-raw '{ "inputs": [ { "uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm", "engine": "FemEngineHD", "localPath": "data/" }, { "uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh" } ], "options": { "poolType": "VM-S-5", "nodeCount": 1 } }'
In the above example, the lake.m21fm will be put in a folder called data like this: {engine working dir}/data/lake.m21fm
It is also possible to specify the file name:
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD",
"localPath": "data/thisIsTheSetupFile.m21fm"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
Click to show example shell script to run an engine execution with specified file name
projectId="<replacewithprojectid>" openapikey="<replacewithopenapikey>" # create execution curl -L -X POST "https://api.mike-cloud-test.com/api/compute/execution" \ -H 'api-version: 2' \ -H 'dhi-service-id: engine' \ -H "dhi-project-id: $projectId" \ -H "dhi-open-api-key: $openapikey" \ -H 'Content-Type: application/json' \ --data-raw '{ "inputs": [ { "uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm", "engine": "FemEngineHD", "localPath": "data/thisIsTheSetupFile.m21fm" }, { "uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh" } ], "options": { "poolType": "VM-S-5", "nodeCount": 1 } }'
In the example above, lake.m21fm will be downloaded to {engine working dir}/data/thisIsTheSetupFile.m21fm
This can be combined for all the input files. E.g. like this:
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lakeone.mesh",
"localPath": "lake.mesh"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/laketwo.mesh",
"localPath": "data/"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lakethree.mesh",
"localPath": "data/mesh/lake.mesh"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
Which will end up in folder structure:
{engine working dir}/lake.m21fm
{engine working dir}/lake.mesh
{engine working dir}/data/laketwo.mesh
{engine working dir}/data/mesh/lake.mesh
Log files updates¶
reportLogUpdatesLines and logFiles are optional parameters used to turn on log updates messages.
reportLogUpdatesLines sets maximum number of lines from the engine log to send with each update (every second). Longer updates are cut to send no more than reportLogUpdatesLines lines. Allowed are values from -1 to 1000. When not set or when it is 0, no log updates are sent. When it is -1, recommended maximal value is used (300).
logFiles specifies updates from what log files are sent. It is list of relative paths to the directory with setup file. When no log files are listed, only [setup_file].log is monitored for updates.
Examples of inputs for FemEngineHD engine:
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD",
"runParameters": [
{
"name": "SubdomainsPerNode",
"value": "2"
},
{
"name": "ThreadsPerSubdomain",
"value": "1"
}
],
"reportLogUpdatesLines": -1
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD",
"runParameters": [
{
"name": "SubdomainsPerNode",
"value": "2"
},
{
"name": "ThreadsPerSubdomain",
"value": "1"
}
],
"reportLogUpdatesLines": -1,
"logFiles": ["lake.log", "lake_p1.log"]
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/examples/fepest-square3/pest/WetRiverValley-p20.fps",
"localPath": "pest/WetRiverValley-p20.fps",
"engine": "FePEST",
"runParameters": [
{
"name": "ThreadsPerWorker",
"value": "1"
},
{
"name": "WorkersPerNode",
"value": "2"
}
]
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/examples/fepest-square3/femdata/WetRiverValley-ready.fem",
"localPath": "femdata/WetRiverValley-ready.fem"
},
"reportLogUpdatesLines": -1,
"logFiles": ["master-out.txt"]
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 2
}
}
Run parameters¶
runParameters are optional parameters used to run the engine. FemEngineHD, FemEngineSW and FemEngineHDGPU support these parameters: SubdomainsPerNode, ThreadsPerSubdomain.
| Engine | Parameter | Details |
|---|---|---|
| FemEngineHD FemEngineSW |
SubdomainsPerNode | Number of subdomains for each computational node. Total number of subdomains is then NodeCount*SubdomainsPerNode. Number of CPU cores is used as number of subdomains when SubdomainsPerNode is missing. |
| FemEngineHDGPU | SubdomainsPerNode | Number of subdomains for each computational node. Total number of subdomains is then NodeCount*SubdomainsPerNode. Number of GPU is used as number of subdomains when SubdomainsPerNode is missing. |
| FemEngineHD FemEngineSW FemEngineHDGPU |
ThreadsPerSubdomain | Number of threads per subdomain. Engine uses all CPU cores when ThreadsPerSubdomain is missing. |
| FePEST | WorkersPerNode | Number of workers to run on each computational node. Only 1 worker is run when WorkersPerNode is missing. |
| FEFLOW FePEST |
ThreadsPerWorker | Number of threads each worker uses. Number of CPU cores is used as number of threads when ThreadsPerWorker is missing. |
Examples of inputs for the different engines:
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD",
"version": "2023.0",
"runParameters": [
{
"name": "SubdomainsPerNode",
"value": "2"
},
{
"name": "ThreadsPerSubdomain",
"value": "1"
}
]
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/examples/MIKE2020/MIKE_21/SW/Lake/Lake.sw",
"engine": "FemEngineSW",
"version": "2023.0",
"runParameters": [
{
"name": "SubdomainsPerNode",
"value": "2"
},
{
"name": "ThreadsPerSubdomain",
"value": "1"
}
]
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/examples/MIKE2020/MIKE_21/SW/Lake/Lake_Mesh.mesh"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/examples/MIKE2020/MIKE_21/SW/Lake/Wind.dfs0"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
{
"inputs": [
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mike1d/Tutor1Base.m1dx",
"engine": "MIKE1D",
"version": "2023.0",
"runParameters": []
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mike1d/Tutor1Base.CRF"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mike1d/Tutor1Base.xns11"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mike1d/Tutor1/RAIN.dfs0",
"localPath": "Tutor1/"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mike1d/Tutor1/WLOUTLET.dfs0",
"localPath": "Tutor1/"
},
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/examples/fepest-square3-flat/square3-ready.fem",
"engine": "FEFLOW",
"runParameters": [
{
"name": "ThreadsPerWorker",
"value": "1"
}
]
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/examples/fepest-square3-flat/square3.fps",
"engine": "FePEST",
"runParameters": [
{
"name": "ThreadsPerWorker",
"value": "1"
}
]
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/examples/fepest-square3-flat/square3-ready.fem"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/examples/fepest-square3-flat/WetRiverValley-p20.fps"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/examples/fepest-square3-flat/WetRiverValley-ready.fem"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 3
}
}
{
"inputs": [
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/MikeSHE_Simple/Example1.she",
"engine": "MIKESHE"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/MikeSHE_Simple/Model%20Domain%20and%20Grid.dfs2"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
{
"inputs": [
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Demo.mhydro",
"engine": "MIKEHYDRObasin"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Catchment%20runoff%20time%20series_C1.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Characteristic%20levels%20time%20series_R5.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Flood%20control%20time%20series%20file_R5.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Head%20loss%20table_H7.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Level%20area%20volume%20table_R5.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Power%20demand%20time%20series_H7.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Power%20efficiency%20table_H7.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Return%20flow%20time%20series_E3.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Return%20flow%20time%20series_E7.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Water%20supply%20fraction%20time%20series_E6.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Water%20use%20time%20series_W2.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydrobasin/Water%20use%20time%20series_W6.dfs0"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
{
"inputs": [
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydroriver/Cali.mhydro",
"engine": "MIKEHYDROriver"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydroriver/CALI-DEMO.dfs0"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydroriver/CALI-HD-HOT.res1d"
},
{
"uri": "https://coreenginedevinputs.blob.core.windows.net/data/mikehydroriver/cali.xns11"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
Output options¶
Setting up the location where the output files (i.e., result and log files created by the engine) will be located can be done by using the output (for any blob container) or platformOutput(for place in MIKE Cloud Platform relative to root project) option. The structure and naming of the files in the output location is defined by the engine used to run the execution.
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
}
],
"output": {
"uri": "https://engineoutput.blob.core.windows.net/thisismyoutputlocation"
},
"platformOutput": [
{
"modelFileName": "lake.m21fm",
"resultsRelativePath": "Results subfolder"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 1
}
}
Running on multiple nodes¶
The user can control how many compute nodes will be used for running an execution by specifying the nodeCount parameter. The following example shows how to start an execution on two compute nodes:
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
}
],
"options": {
"poolType": "VM-S-5",
"nodeCount": 2
}
}
Max execution elapsed time¶
There is a default run limit of 1 day per execution. Meaning if execution is not stopped or provides any result it will be terminated in 1 day. It is possible to override this behaviour using maxExecutionElapsedTimeHours. The number is positive number less then 720(30 days). The following example shows how to start an execution which would have elapsed time set to an hour:
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
}
],
"options": {
"poolType": "VM-S-5",
"maxExecutionElapsedTimeHours": 1,
"nodeCount": 1
}
}
Note
maxExecutionElapsedTimeHours is combined for all setup files per execution.
Uploading partial result files¶
When a simulation is cancelled or unsuccessful partial result files are by default uploaded to the output location. It is possible to override this behaviour by using the uploadOfPartialResults option. Setting this to partialLogs will have the effect that only partial log files resulted from the simulation will be uploaded. It is also possible to disable the upload of all partial files, by setting the value of uploadOfPartialResults to None:
{
"inputs": [
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
"engine": "FemEngineHD"
},
{
"uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
}
],
"options": {
"poolType": "VM-S-5",
"maxExecutionElapsedTimeHours": 1,
"nodeCount": 1,
"uploadOfPartialResults": "None"
}
}