WellEventTimeline

class rips.WellEventTimeline

Bases: PdmObjectBase

Methods Summary

add_control_event([event_date, well_path, ...])

Add a well control event to the timeline

add_keyword_event(event_date, keyword_name, ...)

Add a schedule-level keyword event (not tied to a specific well path).

add_perf_event([event_date, well_path, ...])

Add a perforation event to the timeline

add_raw_text_event(event_date, text[, ...])

Add raw text at a specific position in a dated schedule section.

add_state_event([event_date, well_path, ...])

Add a well state event to the timeline

add_tubing_event([event_date, well_path, ...])

Add a tubing event to the timeline

add_valve_event([event_date, well_path, ...])

Add a valve event to the timeline

add_well_keyword_event(event_date, ...)

Add a well keyword event with arbitrary keyword data.

add_wellspec_event([event_date, well_path, ...])

Add a WELLSPEC event to the timeline

events()

Events

generate_schedule([eclipse_case, ...])

Generate Eclipse schedule text for all wells in the collection

generate_schedule_text(eclipse_case[, ...])

Generate Eclipse schedule text for all wells in the collection.

set_timestamp([timestamp])

Apply well events up to a given timestamp

Methods Documentation

add_control_event(event_date: str = '2024-01-01', well_path: WellPath | None = None, control_mode: ControlMode = ControlMode.ORAT, control_value: float = 0.0, bhp_limit: float = 0.0, oil_rate: float = 0.0, water_rate: float = 0.0, gas_rate: float = 0.0, is_producer: bool = True) → WellEventControl

Add a well control event to the timeline

Parameters:

  • event_date (str) -- Event Date (YYYY-MM-DD)

  • well_path (Optional[WellPath]) -- Well Path

  • control_mode (ControlMode) -- One of [ORAT, WRAT, GRAT, LRAT, RESV, BHP, THP]

  • control_value (float) -- Control Value

  • bhp_limit (float) -- BHP Limit [bar]

  • oil_rate (float) -- Oil Rate [Sm3/day]

  • water_rate (float) -- Water Rate [Sm3/day]

  • gas_rate (float) -- Gas Rate [Sm3/day]

  • is_producer (bool) -- Is Producer

Returns:

WellEventControl

add_keyword_event(event_date: str | date | datetime, keyword_name: str, keyword_data: Dict[str, Any]) → KeywordEvent

Add a schedule-level keyword event (not tied to a specific well path).

This is for global schedule keywords like RPTRST, GRUPTREE, RPTSCHED, etc. that apply to the entire simulation rather than a specific well.

Type inference rules: - str → STRING - int → INT - float → DOUBLE - bool → INT (1 or 0)

Parameters:

  • event_date -- Date string in YYYY-MM-DD format, date, or datetime object

  • keyword_name (str) -- Keyword name (e.g., "RPTRST", "GRUPTREE", "RPTSCHED")

  • keyword_data (dict) -- Dictionary mapping keyword item names to values

Returns:

The created keyword event object

Return type:

KeywordEvent

Raises:

TypeError -- If keyword_data contains unsupported value types

Example

# Get the timeline
well_path_coll = project.descendants(rips.WellPathCollection)[0]
timeline = well_path_coll.event_timeline()

# Add RPTRST - Report restart settings (schedule-level, not well-specific)
timeline.add_keyword_event(
    event_date="2024-01-01",
    keyword_name="RPTRST",
    keyword_data={
        "BASIC": 2,
        "FREQ": 1,
    },
)

# Add GRUPTREE - Group tree definition
timeline.add_keyword_event(
    event_date="2024-01-01",
    keyword_name="GRUPTREE",
    keyword_data={
        "CHILD_GROUP": "OP",
        "PARENT_GROUP": "FIELD",
    },
)

# Add RPTSCHED - Report schedule settings
timeline.add_keyword_event(
    event_date="2024-01-01",
    keyword_name="RPTSCHED",
    keyword_data={
        "FIP": 1,
        "WELLS": 2,
    },
)
add_perf_event(event_date: str = '2024-01-01', well_path: WellPath | None = None, start_md: float = 0.0, end_md: float = 0.0, diameter: float = 0.216, skin_factor: float = 0.0, state: State = State.OPEN, completion_number: int = 0) → WellEventPerf

Add a perforation event to the timeline

Parameters:

  • event_date (str) -- Event Date (YYYY-MM-DD)

  • well_path (Optional[WellPath]) -- Well Path

  • start_md (float) -- Start Measured Depth

  • end_md (float) -- End Measured Depth

  • diameter (float) -- Diameter [m]

  • skin_factor (float) -- Skin Factor

  • state (State) -- One of [OPEN, SHUT]

  • completion_number (int) -- Completion Number (for COMPLUMP, 0 = none)

Returns:

WellEventPerf

add_raw_text_event(event_date: str | date | datetime, text: str, placement: str = 'AFTER_DATE', anchor_keyword: str = '', priority: int = 0) → Any

Add raw text at a specific position in a dated schedule section.

placement is one of AFTER_DATE, BEFORE_KEYWORD, AFTER_KEYWORD, or END_OF_DATE. anchor_keyword is required for before/after-keyword placement and must be empty for the other placements. Lower priority values are emitted first; source order breaks ties.

add_state_event(event_date: str = '2024-01-01', well_path: WellPath | None = None, well_state: WellState = WellState.OPEN) → WellEventState

Add a well state event to the timeline

Parameters:

  • event_date (str) -- Event Date (YYYY-MM-DD)

  • well_path (Optional[WellPath]) -- Well Path

  • well_state (WellState) -- One of [OPEN, SHUT, STOP]

Returns:

WellEventState

add_tubing_event(event_date: str = '2024-01-01', well_path: WellPath | None = None, start_md: float = 0.0, end_md: float = 0.0, inner_diameter: float = 0.15, roughness: float = 1e-05) → WellEventTubing

Add a tubing event to the timeline

Parameters:

  • event_date (str) -- Event Date (YYYY-MM-DD)

  • well_path (Optional[WellPath]) -- Well Path

  • start_md (float) -- Start Measured Depth

  • end_md (float) -- End Measured Depth

  • inner_diameter (float) -- Inner Diameter [m]

  • roughness (float) -- Roughness [m]

Returns:

WellEventTubing

add_valve_event(event_date: str = '2024-01-01', well_path: WellPath | None = None, measured_depth: float = 0.0, valve_type: ValveType = ValveType.ICV, state: State2 = State2.OPEN, flow_coefficient: float = 0.7, area: float = 0.0001, aicd_strength: float = 0.00021, aicd_density_calib_fluid: float = 1000.0, aicd_viscosity_calib_fluid: float = 1.0, aicd_vol_flow_exp: float = 2.1, aicd_visc_func_exp: float = 0.5) → WellEventValve

Add a valve event to the timeline

Parameters:

  • event_date (str) -- Event Date (YYYY-MM-DD)

  • well_path (Optional[WellPath]) -- Well Path

  • measured_depth (float) -- Measured Depth

  • valve_type (ValveType) -- One of [ICV, ICD, AICD]

  • state (State2) -- One of [OPEN, SHUT]

  • flow_coefficient (float) -- Flow Coefficient

  • area (float) -- Area [m2]

  • aicd_strength (float) -- AICD Strength

  • aicd_density_calib_fluid (float) -- AICD Density of Calibration Fluid [kg/m3]

  • aicd_viscosity_calib_fluid (float) -- AICD Viscosity of Calibration Fluid [cP]

  • aicd_vol_flow_exp (float) -- AICD Volume Flow Rate Exponent

  • aicd_visc_func_exp (float) -- AICD Viscosity Function Exponent

Returns:

WellEventValve

add_well_keyword_event(event_date: str | date | datetime, well_path: Any, keyword_name: str, keyword_data: Dict[str, Any]) → WellEventKeyword

Add a well keyword event with arbitrary keyword data.

This is a convenience method that automatically infers types from Python values and calls the underlying GRPC method with parallel arrays.

Type inference rules: - str → STRING - int → INT - float → DOUBLE - bool → INT (1 or 0)

Parameters:

  • event_date -- Date string in YYYY-MM-DD format, date, or datetime object

  • well_path (WellPath) -- The well path object

  • keyword_name (str) -- Keyword name (e.g., "WCONHIST", "WELTARG", "WRFTPLT")

  • keyword_data (dict) -- Dictionary mapping keyword item names to values

Returns:

The created keyword event object

Return type:

WellEventKeyword

Raises:

TypeError -- If keyword_data contains unsupported value types

Example

# Get the timeline
well_path = project.well_paths()[0]
timeline = well_path.event_timeline()

# Add WCONHIST - Historical production data
timeline.add_well_keyword_event(
    event_date="2018-04-01",
    well_path=well_path,
    keyword_name="WCONHIST",
    keyword_data={
        "WELL": well_path.name,
        "STATUS": "OPEN",
        "CMODE": "RESV",
        "ORAT": 3999.98999,
        "WRAT": 0.01,
        "GRAT": 550678.438,
        "VFP_TABLE": 1,
    },
)

# Add WELTARG - Change target
timeline.add_well_keyword_event(
    event_date="2018-05-01",
    well_path=well_path,
    keyword_name="WELTARG",
    keyword_data={
        "WELL": well_path.name,
        "CMODE": "ORAT",
        "NEW_VALUE": 5000.0,
    },
)

# Add WRFTPLT - Enable RFT output
timeline.add_well_keyword_event(
    event_date="2018-06-01",
    well_path=well_path,
    keyword_name="WRFTPLT",
    keyword_data={
        "WELL": well_path.name,
        "OUTPUT_RFT": "YES",
        "OUTPUT_PLT": "NO",
    },
)

# Generate schedule
case = project.cases()[0]
schedule_text = timeline.generate_schedule_text(
    eclipse_case=case, export_msw_for_wells=[well_path]
)
print(schedule_text)
add_wellspec_event(event_date: str = '2024-01-01', well_path: WellPath | None = None, group_name: str = '', allow_cross_flow: bool = True, reference_depth: float | None = None, well_type: WellTypeForExport = WellTypeForExport.OIL) → WellEventWellSpec

Add a WELLSPEC event to the timeline

Parameters:

  • event_date (str) -- Event Date (YYYY-MM-DD)

  • well_path (Optional[WellPath]) -- Well Path

  • group_name (str) -- Group Name

  • allow_cross_flow (bool) -- Allow Well Cross-Flow

  • reference_depth (Optional[Optional[float]]) -- Reference Depth

  • well_type (WellTypeForExport) -- One of [OIL, GAS, WATER, LIQUID]

Returns:

WellEventWellSpec

events() → List[WellEvent]

Events

Returns:

List[WellEvent]

generate_schedule(eclipse_case: Reservoir | None = None, export_msw_for_wells: List[WellPath] = [], first_date_as_comment: bool = True, align_columns: bool = False, additional_dates: List[str] = []) → DataContainerString

Generate Eclipse schedule text for all wells in the collection

Parameters:

  • eclipse_case (Optional[Reservoir]) -- Eclipse Case

  • export_msw_for_wells (List[WellPath]) -- Wells for which multi-segment-well keywords (WELSEGS, COMPSEGS, WSEGVALV, WSEGAICD) are exported

  • first_date_as_comment (bool) -- Emit the first (simulation-start) date as a comment instead of a DATES keyword

  • align_columns (bool) -- Emit a column-header comment and right-aligned, fixed-width columns instead of the compact form

  • additional_dates (List[str]) -- Additional dates (YYYY-MM-DD or full ISO timestamp) emitted as DATES keywords, e.g. to force summary reports at those dates

Returns:

DataContainerString

generate_schedule_text(eclipse_case: EclipseCase, export_msw_for_wells: List[WellPath] = [], first_date_as_comment: bool = True, align_columns: bool = False, additional_dates: List[str] = []) → str

Generate Eclipse schedule text for all wells in the collection.

The timeline is shared across all wells in the well path collection. This method generates schedule data for all wells that have events in the timeline.

This is a convenience wrapper around generate_schedule() that returns the text directly instead of a DataContainerString.

Parameters:

  • eclipse_case (EclipseCase) -- Eclipse case to use for schedule generation.

  • export_msw_for_wells (List[WellPath]) -- Wells for which the multi-segment-well keywords (WELSEGS, COMPSEGS, WSEGVALV, WSEGAICD) are exported. Wells not in the list get no MSW keywords. An empty list (the default) suppresses MSW export for all wells.

  • first_date_as_comment (bool) -- When True (the default), the first (earliest) date is written as a comment line (e.g. "-- Date: 1 JAN 2024") instead of a DATES keyword. This avoids a DATES entry equal to the simulation start date, which some commercial simulators reject. Later dates are always emitted as DATES keywords.

  • align_columns (bool) -- When True, emit each keyword with a "--"-prefixed column-header comment and right-aligned, fixed-width columns instead of the compact default form. Defaults to False.

  • additional_dates (List[str]) -- Additional dates ("YYYY-MM-DD" or a full ISO timestamp such as "2024-05-15T14:45:30") emitted as DATES keywords even when no events fall on them. In Eclipse/Flow a DATES entry ensures a summary report at that date. The dates are merged, deduplicated and sorted together with the event dates, and are not filtered by set_timestamp(). If an additional date precedes all event dates it becomes the earliest date and is therefore emitted as a comment when first_date_as_comment is True; pass first_date_as_comment=False to emit every date as a DATES keyword.

Returns:

Eclipse schedule text containing DATES, COMPDAT, WELSEGS, WCONPROD, etc.

for all wells in the collection.

Return type:

str

Example

# Get the timeline (shared across all wells)
well_path = project.well_paths()[0]
timeline = well_path.event_timeline()

# Add events for multiple wells
timeline.add_perf_event(
    event_date="2024-01-01",
    well_name="WELL-1",
    start_md=1000,
    end_md=1500,
    diameter=0.1,
    skin_factor=0.5,
    state="OPEN",
)

timeline.add_perf_event(
    event_date="2024-02-01",
    well_name="WELL-2",
    start_md=2000,
    end_md=2500,
    diameter=0.1,
    state="OPEN",
)

# Generate schedule text, exporting MSW keywords for all wells
case = project.cases()[0]
schedule_text = timeline.generate_schedule_text(
    eclipse_case=case, export_msw_for_wells=project.well_paths()
)
print(schedule_text)
set_timestamp(timestamp: str = '2024-01-01') → None

Apply well events up to a given timestamp

Parameters:

timestamp (str) -- Timestamp (YYYY-MM-DD)

Returns: