# Survey calculation

In comparison to single-point calculation, survey calculation allows users to perform a series of calculations by varying one or more input variables.

### JSON input (example)

Here two isothermal flash inputs are taken as examples to illustrate the survey calculation input.

{% tabs %}
{% tab title="one survey variable" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "params": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "NACL": 20.0
            }
        },
        "surveyInputs": [
            {
                "variableField": "/params/temperature/value",
                "values": [30.0, 35.0, 40.0, 45.0, 50.0]
            }
        ],
        "surveyOutputsByField": [
            {
                "field": "/solid/trueConcentration/values/NACL",
                "defaultValue": 0
            }
        ]
    }
}
</code></pre>

{% endtab %}

{% tab title="two survey variables" %}

```json
{
    "params": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "NACL": 20.0
            }
        },
        "surveyInputs": [
            {
                "variableField": "/params/temperature/value",
                "values": [30.0, 30.0, 40.0, 40.0, 50.0, 50.0]
            },
            {
                "variableField": "/params/pressure/value",
                "values": [1.0, 1.5, 1.0, 1.5, 1.0, 1.5]
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

| params.surveyInputs[\[ { } \]](/terms-definition.md) | type             | description                                                                                          |
| ---------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| variableField                                        | string           | [JSON pointer](https://datatracker.ietf.org/doc/html/rfc6901) to the survey variable in input schema |
| values                                               | array of numbers | series of survey variable values for calculation                                                     |

The survey calculation runs the series of input JSON by overwriting the survey variable values.&#x20;

{% hint style="warning" %}
When an input variable is specified as a survey variable, e.g. "/params/temperature/value", the source input JSON field, **params.temperature.value**, is optional as it will be overwritten by the survey calculation inputs. However, **params.temperature.unit** is still required.
{% endhint %}

{% hint style="info" %}
When multiple survey variables are specified, the values in each **params.surveyInputs\[{}].values** array are updated simultaneously. When the arrays are specified in different sizes, the last value of the shorter array(s) will be used to run the survey calculation until the longest array is completed.
{% endhint %}

Specific stream output can be shown in an array for user's convinience.&#x20;

| params.surveyOutputsByField | type   | description                                                                                                              |
| --------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| field                       | string | [JSON pointer](https://datatracker.ietf.org/doc/html/rfc6901) to the stream output of interest in the survey calculation |
| defaultValue                | number | optional, default value if specified field in stream output does not exist in specific point                             |

### Response (status = PROCESSED)

```json
{
    "code": 200,
    "result": {
        "surveyOutputs": [
            {
                "phases": {...<snip>...},
                "phaseSummary": [...<snip>...],
                "total": {...<snip>...}
            },
            {...<snip>...},
            {...<snip>...},
            {...<snip>...}
        ]
    },
    "surveyOutputsByField": [
    {
        "field": "/solid/trueConcentration/values/NACL",
        "results": [0.0, 1.35, 1.51, 1.7],
        "presence": [true, true, true, true]
    }],
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

**result.surveyOutputs** list an array of objects as the full [stream output ](/stream-output-json.md)of each survey calculation result. **result.surveyOutputsByField** lists the specific output in one array along the survey calculations.&#x20;

| result.surveyOutputsByField[\[{}\]](/terms-definition.md) | type             | description                                                                                                                                                                                                                        |
| --------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| field                                                     | string           | [JSON pointer](https://datatracker.ietf.org/doc/html/rfc6901) to the stream output of interest in the survey calculation, as specified in input                                                                                    |
| results                                                   | array of numbers | specific values in the stream outputs along the survey calculations                                                                                                                                                                |
| presence                                                  | array of boolean | presence of the specific output. False if the individual calculation inside the survey did not converge. Also false if the specific field does not exist in stream output, unless the "defaultValue" is provided in survey inputs. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devdocs.olisystems.com/survey-calculation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.