# Uncertainty API

The Uncertainty API exposes the ensembles, realizations, and per-realization
results that FDPlan produces when a scenario or virtual scenario is evaluated.

A study's uncertainty method controls how realizations are produced for each
ensemble. With MonteCarlo, realizations are created automatically by Monte
Carlo sampling of the input data sources, and the study's number of
realizations controls how many are generated per scenario. With Deterministic,
you provide the outcomes directly in the input data sources and choose which
realizations to evaluate, for example a curated set of P10, P50, and P90 cases
from an external domain study. Evaluation results are then presented as a range of
outcomes that you can use to interpret uncertainty in the key performance
indicators (KPIs) of decision alternatives.

An ensemble is a collection of realizations produced for a single scenario or
virtual scenario, scoped to a version of a workflow specification. Each
realization pins one container reference per workflow-specification node so
that downstream computations and visualizations read deterministic inputs and
outputs.

Use this API to retrieve an ensemble and its realizations, update an ensemble,
read the per-realization indicator values produced by an evaluation, and read
the computation-event log of a single realization.

## Client ID

* prod-nam-services-fdplan.slbservice.com
* prod-eu-services-fdplan.slbservice.com
* prod-au-services-fdplan.slbservice.com
* prod-id-services-fdplan.slbservice.com
* production-services-fdplan.slbservice.com


# Table of contents

* [Get an ensemble](#get-an-ensemble)
* [Update an ensemble](#update-an-ensemble)
* [Get realization indicators](#get-realization-indicators)
* [Get realization computation events](#get-realization-computation-events)


# Get an ensemble 

Get an ensemble by its identifier, including the realizations it holds and
the container references that each realization pins for every
workflow-specification node.

**Parameters**

* **slb-partition-id** Data partition id.
* **id** The identifier of the ensemble to get.


Example
curl -request GET 
--url 'https://api.delfi.slb.com/fdplan/uncertainty/v1/ensembles/{id}' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header'

Response: 200
{
"Id": "01J55M2WX7Z2NM9APBZ92NTNXY",
"version": 3,
"workflowSpecId": {
"Id": "01E86SDT0780JMFFZHPBV3KVHV",
"version": 1
},
"uncertaintyMethod": "Deterministic",
"tags": [
"StudyId:01J55K2V6T77MRHGT1EZ60KMJ2",
"ScenarioId:01J55M2W4BJA6CGBRCNCK412XZ"
],
"cases": [
],
"realizations": [
{
"Id": "01J55K2V6T77MRHGT1EZ60KMJ2/realizations/01J55M7D63XFJM64GS1N2NNE5V",
"status": "Active",
"version": 7,
"containers": [
{
"address": {
"type": "DataTypeInput",
"computationIndex": 0,
"dataTypeIndex": 0
},
"dataType": {
"Id": "production-forecast",
"version": 1
},
"labels": {
"name": "Field_Profile Upside Base.xlsx"
},
"uri": "01J55K2V6T77MRHGT1EZ60KMJ2/containers/production-forecast/01J55M6YHKR877H2M7C31F3MQY"
},
{
"address": {
"type": "DataTypeOutput",
"computationIndex": 0,
"dataTypeIndex": 0
},
"dataType": {
"Id": "peep-output",
"version": 1
},
"uri": "01J55K2V6T77MRHGT1EZ60KMJ2/containers/peep-output/01J55MH0FYX437F6RDK87BF434"
}
]
}
]
}

[Back to table of contents](#toc)

# Update an ensemble 

Update an existing ensemble. The request body is a JSON Patch document, and
only the replace operation is supported. Use it to change mutable fields,
such as the realizations selected for evaluation.

**Parameters**

* **slb-partition-id** Data partition id.
* **id** The identifier of the ensemble to update.
* **patches** The patches to apply to the ensemble. Only the replace operation is supported.


Example
curl -request PATCH 
--url 'https://api.delfi.slb.com/fdplan/uncertainty/v1/ensembles/{id}' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header' 
--data '[
{
"op": "replace",
"path": "01K21TCP8YRHJP29K3WXACFPKP/realizations/01K21TRKZG07FYG68EW3Y45X7B/status",
"value": "Active"
}
]'

Response: 200
{
"Id": "01J55M2WX7Z2NM9APBZ92NTNXY",
"version": 3,
"workflowSpecId": {
"Id": "01E86SDT0780JMFFZHPBV3KVHV",
"version": 1
},
"uncertaintyMethod": "Deterministic",
"tags": [
"StudyId:01J55K2V6T77MRHGT1EZ60KMJ2",
"ScenarioId:01J55M2W4BJA6CGBRCNCK412XZ"
],
"cases": [
],
"realizations": [
{
"Id": "01J55K2V6T77MRHGT1EZ60KMJ2/realizations/01J55M7D63XFJM64GS1N2NNE5V",
"status": "Active",
"version": 7,
"containers": [
{
"address": {
"type": "DataTypeInput",
"computationIndex": 0,
"dataTypeIndex": 0
},
"dataType": {
"Id": "production-forecast",
"version": 1
},
"labels": {
"name": "Field_Profile Upside Base.xlsx"
},
"uri": "01J55K2V6T77MRHGT1EZ60KMJ2/containers/production-forecast/01J55M6YHKR877H2M7C31F3MQY"
},
{
"address": {
"type": "DataTypeOutput",
"computationIndex": 0,
"dataTypeIndex": 0
},
"dataType": {
"Id": "peep-output",
"version": 1
},
"uri": "01J55K2V6T77MRHGT1EZ60KMJ2/containers/peep-output/01J55MH0FYX437F6RDK87BF434"
}
]
}
]
}

[Back to table of contents](#toc)

# Get realization indicators 

Get the per-realization indicator values produced by the evaluation of the
ensemble. Each entry is keyed on a realization URI and groups its results by
workflow-specification node address. Results are returned in pages controlled
by offset and limit.

**Parameters**

* **slb-partition-id** Data partition id.
* **id** The identifier of the ensemble to get the realization indicators for.
* **offset** The number of realizations to skip before returning indicator results.
* **limit** The maximum number of realizations for which to return indicator results after the offset.


Example
curl -request GET 
--url 'https://api.delfi.slb.com/fdplan/uncertainty/v1/ensembles/{id}/realization-indicators?limit=value&offset=value' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header'

Response: 200
{
"items": [
{
"realizationURI": "01J55K2V6T77MRHGT1EZ60KMJ2/realizations/01J55M7D63XFJM64GS1N2NNE5V",
"results": [
{
"address": {
"type": "DataTypeOutput",
"computationIndex": 0,
"dataTypeIndex": 0
},
"indicators": [
{
"name": "NPV",
"unit": "M$",
"value": "83.59"
},
{
"name": "Total CAPEX",
"unit": "M$",
"value": "9.33"
},
{
"name": "First Oil",
"value": "2020 01"
}
]
}
]
}
]
}

[Back to table of contents](#toc)

# Get realization computation events 

Get the computation-event log for a single realization, identified by its
URI. The log records each computation event, including its status,
timestamp, and any generated log files.

**Parameters**

* **slb-partition-id** Data partition id.
* **realizationURI** The URI of the realization to get the computation events for, for example 01J55K2V6T77MRHGT1EZ60KMJ2/realizations/01J55M7D63XFJM64GS1N2NNE5V.


Example
curl -request GET 
--url 'https://api.delfi.slb.com/fdplan/uncertainty/v1/realization-events?realizationURI=value' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header'

Response: 200
{
"computationEvents": [
{
"computationID": "8eec8a4a52b64d540bdfbf6f534995ea73fb449771d2626e42c36be339bbd315",
"computationName": "economics",
"cases": [
],
"computationEvent": [
{
"eventType": "computation required",
"status": "Running",
"message": "Running",
"timestamp": "2024-08-13T10:28:49.038Z",
"generatedFiles": [
]
},
{
"eventType": "computation completed",
"status": "CompletedSuccessfully",
"message": "Completed successfully",
"timestamp": "2024-08-13T10:28:56.155Z",
"generatedFiles": [
]
}
]
}
]
}

[Back to table of contents](#toc)