Simple execution

Running an execution¶

The POST/api/compute/execution endpoint can be used for starting an engine execution using input files from a blob storage. The endpoint requires the following parameters:

inputs: a list of URLs to the setup files and additional files required to run the setups. The links for which engine is specified are considered to be setup files (see Engines for available engine types). If multiple setup files are provided, the engine will execute them in the order given by the user in the list of inputs. All the links to inputs must be accessible as they are.
poolType: the pool configuration that engine execution will be performed on (see Pool types).
nodeCount: number of compute nodes (i.e., virtual machines) on which engine execution will be performed.

Click to show example input to start an engine execution


{
  "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": 1
  }
}

Click to show example shell script to start an engine execution


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"
        },
        {
          "uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
        }
      ],
      "options": {
        "poolType": "VM-S-5",
        "nodeCount": 1
      }
    }'

The endpoint returns:

executionId: the id of the current engine execution (see Track an execution).
outputLocation: the location where the files created by the engine during execution (i.e., result and log files) are stored (see Obtain the results).

Click to show an example of the endpoint's response


{
  "executionId": "97437242-f0f7-433c-94cb-8082bef1d138",
  "outputLocation": "https://coreenginedevdata.blob.core.windows.net/97437242-f0f7-433c-94cb-8082bef1d138?sv=2018-03-28&sr=c&sig=Ec263t1VLiJrtk28SLytNDhRhoCXNFA035MtmQR3Qok%3D&se=2019-10-16T14%3A05%3A17Z&sp=rl"
}

Note

Details about running an execution using data stored in the MIKE Cloud Platform can be found here.

The execution can run only when the ENGINE_EXECUTION feature is enabled and under the allowed project, the second required condition is the sufficient credit balance (see Credits section).

Credits¶

All Engines execution use the credit system to not execute simulation without sufficient balance of credits. Credits are deduced according to maxExecutionElapsedTimeHours ahead and refund the difference between the simulation execution time and ahead deduced amount of credits. In case of insufficient credit balance the execution request ends with HTTP 402: Payment Required status and no simulation is started.

The credits are assigned per customer, the current balance can be obtained by using the GET/api/admin/credit/ endpoint.

Click to show an example of the endpoint's response


{
    "credits": 983800.0
}

Note

Deduce and refund calculation formula

Prize of node type * Number of nodes * execution time in seconds

e.g.:

When - VM-S-40 node is prized 1 credit per second per node - two nodes are requested - simulation takes 2 minutes - maxExecutionElapsedTimeHours parameter is not passed, the default value 24h is used

Deduce of credits at beginning

1 * 2 * (24 * 60 * 60) = 172800

Refund of credits at simulation finished

1 * 2 * ((24 * 60 * 60) - (2 * 60)) = 172560

Tracking an execution¶

Details regarding the execution, including its current status, can be obtained by using the GET/api/compute/execution/{id} endpoint. The response of the endpoint includes:

the status of the execution (status, see Execution statuses for details)
the engine progress for the setup file currently executing (runningSetupProgress)
the total number of setup files given as input to the execution (totalNumberOfSetups)

Click to show an example of the endpoint's response


{
  "executionId": "97437242-f0f7-433c-94cb-8082bef1d138",
  "outputLocation": "https://coreenginedevdata.blob.core.windows.net/97437242-f0f7-433c-94cb-8082bef1d138?sv=2018-03-28&sr=c&sig=Ec263t1VLiJrtk28SLytNDhRhoCXNFA035MtmQR3Qok%3D&se=2019-10-16T14%3A05%3A17Z&sp=rl"
  "status": "InProgress",
  "message": null
  "projectId": "7da87338-ae51-466a-96a9-258162f39784",
  "customerId": "8eb87858-046e-4a92-a739-e4668ed9d1fb",
  "createdAt": "2019-12-19T17:24:25.2581912Z",
  "startedAt": "2019-12-19T17:24:27.2704876Z",
  "updatedAt": "2019-12-19T17:24:27.270486Z",
  "finishedAt": null,
  "engines": [
      {
          "name": "FemEngineHD",
          "version": "2021.0"
      }
  ],
  "poolType": "VM-S-5",
  "virtualMachineSize": "STANDARD_DS2_v2",
  "nodeCount": 1,
  "runningSetupIndex": 0,
  "runningSetupProgress": "STATUS : 2004-01-01 02:21:00, MESSAG : Time step: 4230, COMSPD : 981736, PROGRE : 587, TIMLFT : 2",
  "totalNumberOfSetups": 1
}

Obtaining the execution result files¶

Once the execution finishes, the result of the simulation (including log files created by the engine) can be accessed by using Azure Storage Explorer. This can be done by copying the SAS Uri outputLocation from e.g., the output of the GET/api/compute/execution/{id} endpoint and following the steps described in the Azure Storage Explorer documentation.