primo-optimizer 0.1__py3-none-any.whl

primo/__init__.py

@@ -0,0 +1,13 @@
+#################################################################################
+# PRIMO - The P&A Project Optimizer was produced under the Methane Emissions Reduction Program (MERP)
+# and National Energy Technology Laboratory's (NETL) National Emissions Reduction Initiative (NEMRI).
+#
+# NOTICE. This Software was developed under funding from the U.S. Government and the U.S.
+# Government consequently retains certain rights. As such, the U.S. Government has been granted for
+# itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in
+# the Software to reproduce, distribute copies to the public, prepare derivative works, and perform
+# publicly and display publicly, and to permit others to do so.
+#################################################################################
+
+RELEASE = "0.1.dev0"
+VERSION = "0.1"

primo/data_parser/__init__.py

@@ -0,0 +1,10 @@
+#################################################################################
+# PRIMO - The P&A Project Optimizer was produced under the Methane Emissions Reduction Program (MERP)
+# and National Energy Technology Laboratory's (NETL) National Emissions Reduction Initiative (NEMRI).
+#
+# NOTICE. This Software was developed under funding from the U.S. Government and the U.S.
+# Government consequently retains certain rights. As such, the U.S. Government has been granted for
+# itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in
+# the Software to reproduce, distribute copies to the public, prepare derivative works, and perform
+# publicly and display publicly, and to permit others to do so.
+#################################################################################

primo/data_parser/data_model.py

@@ -0,0 +1,197 @@
+#################################################################################
+# PRIMO - The P&A Project Optimizer was produced under the Methane Emissions Reduction Program (MERP)
+# and National Energy Technology Laboratory's (NETL) National Emissions Reduction Initiative (NEMRI).
+#
+# NOTICE. This Software was developed under funding from the U.S. Government and the U.S.
+# Government consequently retains certain rights. As such, the U.S. Government has been granted for
+# itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in
+# the Software to reproduce, distribute copies to the public, prepare derivative works, and perform
+# publicly and display publicly, and to permit others to do so.
+#################################################################################
+
+# Standard lib
+from __future__ import annotations
+from dataclasses import dataclass
+import logging
+from typing import Dict, Union
+
+
+# User defined lib
+from primo.utils.geo_utils import get_distance
+from primo.utils.raise_exception import raise_exception
+
+LOGGER = logging.getLogger(__name__)
+
+# TODO: Write tests for entire module
+
+
+@dataclass(frozen=True)
+class Well:
+    """
+    A Well dataclass
+    """
+
+    __slots__ = (
+        "well_id",
+        "lat",
+        "long",
+        "score",
+        "is_disadvantaged",
+    )
+    well_id: str
+    lat: Union[float, None]
+    long: Union[float, None]
+    score: float
+    is_disadvantaged: bool
+
+    def haversine_distance(self, other_well: Well) -> float:
+        """
+        Returns the distance in miles between two wells calculated with Haversine formula.
+
+        Parameters
+        ----------
+        other_well : Well
+            The other well under consideration
+
+        Returns
+        -------
+        distance : float
+            The distance between self and other_well
+        """
+        origin = (self.lat, self.long)
+        dest = (other_well.lat, other_well.long)
+        return get_distance(origin, dest)
+
+
+@dataclass(frozen=True)
+class CampaignCandidates:
+    """
+    A dataclass that combines wells that are potential candidates to be included
+    in a plugging campaign
+    """
+
+    __slots__ = ("campaign_id", "well_dict", "n_wells")
+    campaign_id: str
+    well_dict: Dict[str, Well]
+    n_wells: int
+
+    def __post_init__(self):
+        """
+        Run some validation checks
+        """
+        for well_id, well in self.well_dict.items():
+            if well_id != well.well_id:
+                msg = (
+                    f"Dictionary for {self.campaign_id} is corrupted. Expect key "
+                    "to be the same as well_id"
+                )
+                raise_exception(msg, ValueError)
+
+        if self.n_wells != len(self.well_dict):
+            LOGGER.warning(
+                f"{self.n_wells} incorrectly initialized for {self.campaign_id}"
+            )
+            LOGGER.warning("Automatically correcting!")
+            self.n_wells = len(self.well_dict)
+
+
+@dataclass(frozen=True)
+class OptInputs:
+    """
+    Succinctly captures all inputs relevant to the optimization model
+    """
+
+    __slots__ = (
+        "well_dict",
+        "campaign_candidates",
+        "budget",
+        "mobilization_cost",
+        "owner_well_count",
+        "max_wells_per_owner",
+        "dac_budget_fraction",
+        "distance_threshold",
+    )
+    well_dict: Dict[str, Well]
+    campaign_candidates: Dict[str, CampaignCandidates]
+    budget: float
+    mobilization_cost: Dict[int, float]
+    owner_well_count: Dict[str, Well]
+    max_wells_per_owner: float
+    dac_budget_fraction: float
+    distance_threshold: float
+
+    def __post_init__(self):
+        """
+        Run some validation checks
+        """
+        # Create a set to retrieve unique well_id (identifiers that do not repeat).
+        well_id_set = set(self.well_dict.keys())
+
+        if self.budget <= 0:
+            msg = f"Budget cannot be negative. Received " f"{self.budget} for budget."
+            raise_exception(msg, ValueError)
+
+        for well_id, well in self.well_dict.items():
+            if well_id != well.well_id:
+                msg = (
+                    f"Dictionary for optimization inputs corrupted. "
+                    f"Expect key: {well_id} to be the same as"
+                    f" well_id: {well.well_id}"
+                )
+                raise_exception(msg, ValueError)
+
+        max_wells = 0
+        # Iterate through each campaign using its campaign_id.
+        for campaign_id, campaign in self.campaign_candidates.items():
+            # Lines 167-173 aim to verify the accuracy of the
+            # campaign_candidates construction.
+            if campaign_id != campaign.campaign_id:
+                msg = (
+                    f"Dictionary of candidates corrupted. "
+                    f"Expect key: {campaign_id} to be the same as "
+                    f"campaign_id: {campaign.campaign_id}"
+                )
+                raise_exception(msg, ValueError)
+
+            for well_id in campaign.well_dict:
+                # Lines 178-183 aim to verify whether the wells in CampaignCandidates
+                # are all sourced from the input well data.
+                if well_id not in self.well_dict:
+                    msg = (
+                        f"Campaign candidate: {campaign_id} includes well: {well_id}"
+                        f". This well is not provided in well_dict"
+                    )
+                    raise_exception(msg, ValueError)
+
+                # Lines 187-190 aim to check if a well appears more than once within
+                # the same campaign or across different campaigns.
+                if well_id not in well_id_set:
+                    msg = f"Well: {well_id} is included in multiple clusters (campaign candidates)."
+                    raise_exception(msg, ValueError)
+                well_id_set.remove(well_id)
+                # Remove a well_id from the well_id_set the first time it is checked. If the well_id
+                # appears a second time and has already been removed from the unique well_id_set,
+                # an error message on line 188 will be raised.
+                # Each cluster represents a campaign candidate.
+
+            max_wells = max(max_wells, len(campaign.well_dict))
+
+        # Upon iterating through all campaigns and well_ids within those campaigns, all
+        # well_ids in well_id_set should be dropped. If not, it indicates that not all wells
+        # are assigned to a cluster during the clustering step. An error message will be raised at
+        #  Line 202.
+        if well_id_set:
+            msg = "The clustering is not exhaustive."
+            raise_exception(msg, ValueError)
+        for n_wells in range(1, max_wells + 1):
+            cost = self.mobilization_cost.get(n_wells)
+            if cost is None:
+                msg = f"Mobilization cost for n_wells: {n_wells} is missing"
+                raise_exception(msg, ValueError)
+
+            if cost < 0:
+                msg = (
+                    f"Mobilization cost for campaign with n_wells: {n_wells}"
+                    f" is negative: {cost}"
+                )
+                raise_exception(msg, ValueError)

primo/data_parser/input_parser.py

@@ -0,0 +1,161 @@
+#################################################################################
+# PRIMO - The P&A Project Optimizer was produced under the Methane Emissions Reduction Program (MERP)
+# and National Energy Technology Laboratory's (NETL) National Emissions Reduction Initiative (NEMRI).
+#
+# NOTICE. This Software was developed under funding from the U.S. Government and the U.S.
+# Government consequently retains certain rights. As such, the U.S. Government has been granted for
+# itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in
+# the Software to reproduce, distribute copies to the public, prepare derivative works, and perform
+# publicly and display publicly, and to permit others to do so.
+#################################################################################
+
+# Standard libs
+import argparse
+import logging
+import os
+from typing import Dict
+
+# Installed libs
+import pandas as pd
+
+# User-defined libs
+from primo.data_parser.data_model import CampaignCandidates, OptInputs, Well
+from primo.utils.raise_exception import raise_exception
+
+LOGGER = logging.getLogger(__name__)
+
+
+class InputParser:
+    """
+    InputParser class
+    Implements methods for parsing input data from csv
+    """
+
+    def __init__(self, args: argparse.Namespace):
+        """
+        Initialize the class and read in a CSV file.
+
+        Parameters
+        ----------
+        args : argparse.Namespace
+            The arguments parsed from the command line.
+
+        Raises
+        ------
+        ValueError
+            If the specified file does not exist or is not a CSV file.
+        """
+        file_path = args.input_file
+        # Check 1: Check file exists
+        if not os.path.exists(file_path):
+            raise_exception(f"File: {file_path} does not exist.", ValueError)
+
+        # Check 2: Check file is a csv file
+        if file_path.suffix != ".csv":
+            raise_exception(
+                f"File: {file_path} is expected to be an csv file", ValueError
+            )
+
+        self.well_data = pd.read_csv(file_path)
+        self.args = args
+        LOGGER.info(f"Initialized class and read file: {file_path}")
+
+    def parse_data(
+        self,
+        mobilization_cost: Dict[int, float],
+    ) -> OptInputs:
+        """
+        Parse data to create an OptInputs object that models all input parameters
+        to set up the optimization model.
+
+        Parameters
+        ----------
+        mobilization_cost : Dict[int, float]
+            The cost associated with mobilization for a campaign based on the number
+            of wells in a campaign.
+
+        Returns
+        -------
+        opt_inputs : OptInputs
+            A fully instantiated object for inputs to the optimization model.
+
+        Raises
+        ------
+        ValueError
+            If a well ID is repeated in the CSV file.
+        """
+        budget = self.args.total_budget
+        max_wells_per_owner = self.args.max_wells_per_owner
+        well_dict = {}
+        candidates = {}
+        # dac_budget_fraction is the percentage of budget that needs
+        # to be spent on plugging wells in the disadvantaged community
+        dac_budget_fraction = self.args.dac_weight_percent
+        distance_threshold = self.args.maximum_well_distance
+
+        # new data
+        owner_well_count = (
+            self.well_data.groupby("Operator Name")["Well ID"].apply(list).to_dict()
+        )
+
+        dac_weight = self.args.dac_weight
+
+        if self.args.dac_weight_percent is not None:
+            if dac_weight is not None:
+                threshold = dac_weight / 100 * self.args.dac_weight_percent
+            else:
+                raise_exception(
+                    "Disadvantaged Community Impact must be selected as a "
+                    "priority factor if you wish to implement the DAC constraint.",
+                    ValueError,
+                )
+        else:
+            # When the user does not provide a value for disadvantaged community,
+            # all wells are set as not disadvantaged.
+            # The maximum score possible for disadvantaged_community_score is 100.
+            threshold = 100
+        for _, row in self.well_data.iterrows():
+            well_id = row["Well ID"]
+            lat = row["Latitude"]
+            long = row["Longitude"]
+            score = row["Priority Score [0-100]"]
+            if dac_weight is not None:
+                disadvantaged_community_score = row[f"DAC Score [0-{int(dac_weight)}]"]
+                is_disadvantaged = float(disadvantaged_community_score > threshold)
+            else:
+                # When the user does not select DAC as a priority factor,
+                # all wells are assumed to not be located in a disadvantaged community.
+                is_disadvantaged = float(False)
+
+            if well_id in well_dict:
+                msg = f"Well id must be unique. Well id: {well_id} is repeated in csv file"
+                raise_exception(msg, ValueError)
+
+            well_dict[well_id] = Well(well_id, lat, long, score, is_disadvantaged)
+
+        LOGGER.info("Parsing for campaign candidates")
+
+        for _, row in self.well_data.iterrows():
+            well_id = row["Well ID"]
+            cluster = row["cluster"]
+            if cluster not in candidates:
+                candidates.setdefault(cluster, {})
+            candidates[cluster][well_id] = well_dict[well_id]
+
+        campaign_candidates = {}
+        for campaign_id, campaign_dict in candidates.items():
+            LOGGER.info(f"Preparing cluster: {campaign_id}")
+            campaign_candidates[campaign_id] = CampaignCandidates(
+                campaign_id, campaign_dict, len(campaign_dict)
+            )
+
+        return OptInputs(
+            well_dict,
+            campaign_candidates,
+            budget,
+            mobilization_cost,
+            owner_well_count,
+            max_wells_per_owner,
+            dac_budget_fraction,
+            distance_threshold,
+        )

primo/opt_model/__init__.py

@@ -0,0 +1,13 @@
+#################################################################################
+# PRIMO - The P&A Project Optimizer was produced under the Methane Emissions Reduction Program (MERP)
+# and National Energy Technology Laboratory's (NETL) National Emissions Reduction Initiative (NEMRI).
+#
+# NOTICE. This Software was developed under funding from the U.S. Government and the U.S.
+# Government consequently retains certain rights. As such, the U.S. Government has been granted for
+# itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in
+# the Software to reproduce, distribute copies to the public, prepare derivative works, and perform
+# publicly and display publicly, and to permit others to do so.
+#################################################################################
+
+# Optimization Feasibility tolerance
+FEASIBILITY_TOLERANCE = 1e-6

primo/opt_model/base_model.py

@@ -0,0 +1,188 @@
+#################################################################################
+# PRIMO - The P&A Project Optimizer was produced under the Methane Emissions Reduction Program (MERP)
+# and National Energy Technology Laboratory's (NETL) National Emissions Reduction Initiative (NEMRI).
+#
+# NOTICE. This Software was developed under funding from the U.S. Government and the U.S.
+# Government consequently retains certain rights. As such, the U.S. Government has been granted for
+# itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in
+# the Software to reproduce, distribute copies to the public, prepare derivative works, and perform
+# publicly and display publicly, and to permit others to do so.
+#################################################################################
+
+# Standard libs
+from abc import ABC, abstractmethod
+import logging
+import os
+import pathlib
+from typing import Dict, Union
+
+# Installed libs
+import pyomo
+import pyomo.environ as pyo
+from pyomo.contrib.iis import write_iis
+
+# User defined libs
+from primo.utils import get_solver
+
+LOGGER = logging.getLogger(__name__)
+
+
+class BaseModel(ABC):
+    """
+    Base Optimization Model class. To be inherited and used as needed
+    """
+
+    def __init__(self, model_name: str):
+        """
+        Initializes the base model class.
+
+        Parameters
+        ----------
+        model_name : str
+            A string identifier to be assigned to the optimization model
+
+        Returns
+        -------
+        BaseModel
+            A fully instantiated BaseModel object
+        """
+        self.model_name = model_name
+        self.model = pyo.ConcreteModel()
+
+    @abstractmethod
+    def _add_variables(self) -> None:
+        pass
+
+    @abstractmethod
+    def _add_constraints(self) -> None:
+        pass
+
+    def _set_objective(self) -> None:
+        """
+        Override method as needed. By default, assumes that we have a
+        feasibility problem
+        """
+        self.model.obj = pyo.Objective(expr=(0), sense=pyo.minimize)
+
+    def build_model(self) -> None:
+        """
+        Initializes a model to represent the optimization problem at hand
+        """
+        self._add_variables()
+        self._add_constraints()
+        self._set_objective()
+
+    def solve_model(
+        self, solver_params: Dict = {}
+    ) -> pyomo.opt.results.results_.SolverResults:
+        """
+        Solve the optimization model that has previously been set up using
+        the `build_model()` method.
+
+        Parameters
+        ----------
+        solver_params : Dict, optional
+            A dictionary specifying solver parameters and values for them to be used.
+            Valid options include "solver," "stream_output," "mip_gap," "time_limit,"
+            and "solver_options"
+
+        Returns
+        -------
+        results
+            The Pyomo results object
+        """
+        solver = get_solver(**solver_params)
+        results = solver.solve(self.model)
+
+        return results
+
+    def get_model_objective(self) -> float:
+        """
+        Return the objective value for a solved model.
+
+        Note:
+            You are responsible for checking if the model was solved successfully
+
+        Returns
+        -------
+        float
+            The objective value for the solved model. Maybe feasible, optimal,
+            or meaningless
+        """
+        obj_list = []
+        for v in self.model.component_data_objects(pyo.Objective):
+            obj_list.append(v)
+
+        if len(obj_list) == 0:
+            LOGGER.warning("No objectives found in the model.")
+            return
+
+        elif len(obj_list) == 1:
+            return pyo.value(obj_list[0])
+
+        elif len(obj_list) > 1:
+            LOGGER.warning(
+                "Found multiple objectives in the model. Returning all of them."
+            )
+            return {obj.name: pyo.value(obj) for obj in obj_list}
+
+    def write_model(self, file_name: str) -> None:
+        """
+        Writes the optimization model to a file that has previously been set up using
+        :py:meth:`base_model.BaseModel.build_model()` method.
+        The format of the file depends on the filename provided.
+        If the filename ends with .mps, MPS format is used. If the filename
+        ends with .lp, LP format is used. If the filename ends with .rew, a file in
+        MPS format is written with all symbol information stripped.
+
+        Parameters
+        ----------
+        file_name : str
+            The path where the model is to be written.
+            Must end with .mps or .lp extension
+        """
+        ext = pathlib.Path(file_name).suffix
+
+        if ext in (".lp", ".mps", ".rew"):
+            LOGGER.info(f"The model will be written in {ext[1:].upper()} format")
+
+        else:
+            LOGGER.warning(
+                f"Unknown format {ext} encountered for optimization " "model. "
+            )
+            LOGGER.warning("Skipping write_model")
+            return
+
+        if os.path.exists(file_name):
+            LOGGER.warning(f"File: {file_name} exists and will be overwritten")
+
+        if ext in (".lp", ".mps"):
+            # Ask Pyomo to explicitly retain all symbols
+            self.model.write(file_name, io_options={"symbolic_solver_labels": True})
+        else:
+            temp_file_name = file_name[:-4] + ".mps"
+            self.model.write(temp_file_name)
+            os.rename(temp_file_name, file_name)
+
+    def write_iis(self, iis_name: str, solver: Union[str, None] = None) -> None:
+        """
+        For an infeasible model, computes and writes an IIS to the file specified
+        by iis_name. This assumes that a model has been built and solved by calling
+        methods :py:meth:`base_model.BaseModel.build_model()` and
+        :py:meth:`base_model.BaseModel.solved_model()` respectively and has been found
+        to be infeasible.
+
+        Parameters
+        ----------
+        iis_name : str
+            The path where a valid IIS is to be written
+
+        solver : str, optional
+            The solver to be utilized for IIS calculation.
+            Used by Pyomo, ignored if method_api is Gurobipy
+        """
+
+        if os.path.exists(iis_name):
+            LOGGER.warning(f"File: {iis_name} exists and will be overwritten")
+
+        write_iis(self.model, iis_name, solver, LOGGER)