Operations Overview

This document provides a detailed overview of operations in an economic model. The model has two main sections: curtailment (an array of production curtailment entries) and shutIn (an object containing scheduled shut-in periods). A ratioStreamBehavior field controls how ratio streams are handled.

Example Response

{
    "id": "64aa0a00c7852a5f3ad12f64",
    "copiedFrom": null,
    "name": "Operations Demo",
    "tags": ["63b85737ff846cee7b1f6fdc"],
    "unique": true,
    "createdBy": "6234d6677118ecb7e6fd699a",
    "lastUpdatedBy": "6234d6677118ecb7e6fd699a",
    "createdAt": "2023-06-26T23:38:24.574Z",
    "updatedAt": "2023-06-26T23:38:24.574Z",
    "econModelType": "Operations",
    "scenario": "63b8571d70ed63f50bd6d63f",
    "well": "63b85759e1d7eb4e31579f51",
    "ratioStreamBehavior": "default",
    "curtailment": [
        {
            "key": "oil",
            "category": "curtailment",
            "criteria": "entire_well_life",
            "period": ["Flat"],
            "value": [10],
            "unit": "pct_capacity"
        },
        {
            "key": "gas",
            "category": "curtailment",
            "criteria": "offset_to_fpd",
            "period": [6, 12],
            "value": [50, 25],
            "unit": "mcf_per_day",
            "description": "Gas curtailment ramp-down"
        },
        {
            "key": "water",
            "category": "curtailment",
            "criteria": "dates",
            "period": ["2024-01-01", "2025-01-01"],
            "value": [80, 40],
            "unit": "bbl_per_day"
        },
        {
            "key": "oil",
            "category": "curtailment",
            "criteria": "seasonal",
            "period": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
            "value": [90, 85, 80, 75, 70, 65, 60, 65, 70, 75, 80, 85],
            "unit": "pct_capacity"
        }
    ],
    "shutIn": {
        "rows": [
            {
                "phase": "all",
                "dates": {
                    "startDate": "2024-03-01",
                    "endDate": "2024-03-15"
                },
                "repeatRangeOfDates": "yearly",
                "totalOccurrences": 3,
                "unit": "day",
                "multiplier": 0,
                "scalePostShutInEndCriteria": "econ_limit",
                "scalePostShutInEnd": "",
                "fixedExpense": true,
                "capex": false
            }
        ]
    }
}

Data Structure

• ratioStreamBehavior: (required) Controls how ratio streams are computed. See ratioStreamBehavior.
• curtailment: (required) An array of production curtailment row objects. Maximum 43 rows. See curtailment.
• shutIn: (optional) An object containing scheduled shut-in periods. See shutIn.

curtailment

Each element in the curtailment array is an object defining a production limit for a specific stream and time period.

Required fields

• key: (required) The production stream this row applies to. See key.
• category: (required) Must always be "curtailment".
• criteria: (required) The timing basis for the curtailment schedule. See criteria.
• value: (required) An array of numbers representing the curtailment level for each segment. For entire_well_life, a single number or single-element array. For seasonal, exactly 12 numbers. Range: -100000000 to 100000000. See value.
• unit: (required) The unit of measurement for value entries. Valid values depend on key. See unit and the key → unit constraints.

Optional fields

• period: (optional, required for offset_to_as_of_date, offset_to_fpd, and dates criteria) An array whose element type depends on criteria. See period.
• description: (optional) A free-text description of the row. Maximum 500 characters.

"curtailment": [
    {
        "key": "oil",
        "category": "curtailment",
        "criteria": "entire_well_life",
        "value": [10],
        "unit": "pct_capacity"
    }
]

shutIn

The shutIn object contains a rows array of shut-in period definitions.

• rows: (required) An array of shut-in row objects. Maximum 100 rows. Each row must define its timing using either offsetToAsOf or dates (mutually exclusive). See shutIn rows.

shutIn rows

Each element in the shutIn.rows array is an object with the following properties:

Required fields

• phase: (required) The production phase affected by the shut-in. See phase.
• multiplier: (required) A number from 0 (exclusive) to 1000 (inclusive) representing the production multiplier during the shut-in period.
• scalePostShutInEndCriteria: (required) The method used to determine when post-shut-in scaling ends. See scalePostShutInEndCriteria.
• fixedExpense: (required) Boolean. When true, fixed expenses continue to accrue during the shut-in period.
• capex: (required) Boolean. When true, capital expenditures are applied during the shut-in period.

Timing fields (one required)

Each row must include exactly one of:

• offsetToAsOf: An object with start and end properties (numbers from 1 to 1000000) defining the shut-in window as months offset from the as-of date.
• dates: An object with startDate and endDate properties (ISO date strings YYYY-MM-DD, range 1900-01-01 to 2262-04-01) defining an explicit calendar window.

Conditional fields

• unit: The time unit for the shut-in duration.
  • Required when using offsetToAsOf. Valid values: "day" or "month".
  • Required when using dates. Must be "day".
• repeatRangeOfDates: How the shut-in period repeats.
  • When using offsetToAsOf: must be "no_repeat".
  • When using dates: valid values are "no_repeat", "monthly", or "yearly".
• totalOccurrences: The number of times the shut-in repeats.
  • When using offsetToAsOf: must be 1.
  • When using dates: integer from 1 to 1200.
• scalePostShutInEnd: The endpoint value for post-shut-in scaling.
  • Required when scalePostShutInEndCriteria is "offset_to_as_of_date": a stringified integer from 1 to 1000000.
  • Required when scalePostShutInEndCriteria is "dates": an ISO date string (YYYY-MM-DD, range 1900-01-01 to 2262-04-01).
  • Must be empty or omitted when scalePostShutInEndCriteria is "econ_limit".

Definitions

criteria

The timing or rate basis used to segment the curtailment schedule.

• "entire_well_life" — A single flat value applied for the entire well life. period is not required; value must be a single number or single-element array.
• "offset_to_as_of_date" — Months offset from the as-of date. period is required: a number or array of numbers from 1 to 1000000.
• "offset_to_fpd" — Months offset from first production date. period is required: a number or array of numbers from 1 to 1000000.
• "dates" — Calendar date boundaries. period is required: an ISO date string (YYYY-MM-DD) or array of date strings (range 1900-01-01 to 2262-04-01).
• "seasonal" — Monthly seasonal pattern. period may be an array of 12 month labels (Jan–Dec) or null/omitted. value must be exactly 12 numbers.

key

The production stream this curtailment row applies to. Possible values are:

• "oil" — Oil stream.
• "gas" — Gas stream.
• "water" — Water stream.
• "_project_custom_stream_0" through "_project_custom_stream_19" — Project-level custom streams.
• "customNumber0" through "customNumber19" — Custom numeric streams.

Key and unit constraints

key	Allowed unit values
oil	pct_capacity, bbl_per_day
gas	pct_capacity, mcf_per_day
water	pct_capacity, bbl_per_day
_project_custom_stream_0..19, customNumber0..19	pct_capacity, unit_per_day

period

An array whose element type and format depend on the criteria value. period and value arrays must always have the same length (except for seasonal which always has 12 entries).

criteria	period format	Range / Length
entire_well_life	Not required (omit or use "Flat")	N/A
offset_to_as_of_date, offset_to_fpd	Number or array of numbers	1 – 1000000 per item
dates	ISO date string (YYYY-MM-DD) or array of such	1900-01-01 – 2262-04-01
seasonal	Array of 12 month labels (Jan–Dec), or null/omitted	Exactly 12 items

phase

The production phase affected by a shut-in row. Possible values are:

• "all" — All production phases.
• "oil" — Oil only.
• "gas" — Gas only.
• "water" — Water only.

ratioStreamBehavior

A string controlling how ratio-derived streams are calculated. Possible values are:

• "default" — Standard ratio stream calculation.
• "legacy" — Legacy ratio stream calculation behavior.

scalePostShutInEndCriteria

A string defining how post-shut-in production scaling is terminated. Possible values depend on the timing method used:

• When using offsetToAsOf:
  • "offset_to_as_of_date" — Scaling ends at a month offset from the as-of date. scalePostShutInEnd must be provided.
  • "econ_limit" — Scaling continues to the economic limit. scalePostShutInEnd must be empty.
• When using dates:
  • "dates" — Scaling ends at a specific calendar date. scalePostShutInEnd must be provided.
  • "econ_limit" — Scaling continues to the economic limit. scalePostShutInEnd must be empty.

unit (curtailment)

The unit of measurement applied to each value entry in a curtailment row. Valid values depend on key — see the key → unit constraints.

• "pct_capacity" — Percentage of production capacity. Valid for all streams.
• "bbl_per_day" — Barrels per day. Valid for oil and water streams.
• "mcf_per_day" — Thousand cubic feet per day. Valid for gas stream only.
• "unit_per_day" — Generic units per day. Valid for custom streams only.

value

An array of numbers representing the curtailment level for each period segment. Range: -100000000 to 100000000.

• For entire_well_life: a single number or single-element array.
• For offset_to_as_of_date, offset_to_fpd, and dates: a number or array of numbers matching the length of period.
• For seasonal: exactly 12 numbers (one per calendar month, Jan–Dec).