scoptimize.network

  1import pulp
  2import type_enforced
  3from .utils import large_m, Error
  4
  5
  6@type_enforced.Enforcer
  7class NetworkStructure(Error):
  8    def __init__(
  9        self,
 10        name: str,
 11        cashflow_for_use: [int, float] = 0,
 12        cashflow_per_unit: [int, float] = 0,
 13        min_units: [int, float] = 0,
 14        max_units: [int, float] = 0,
 15    ):
 16        """
 17        Initialize a generic network structure object.
 18
 19        Requires:
 20
 21        - `name`:
 22            - Type: str
 23            - What: The name of this network object
 24        - `cashflow_for_use`:
 25            - Type: int | float
 26            - What: The fixed cashflow that occurs if a non zero number of units flow through this network structure
 27        - `cashflow_per_unit`:
 28            - Type: int | float
 29            - What: The cashflow that occurs for each unit that flows through this network structure
 30        - `min_units`:
 31            - Type: int | float
 32            - What: The minimum units that must flow through this network structure
 33        - `max_units`:
 34            - Type: int | float
 35            - What: The maximum units that must flow through this network structure
 36            - Note: `max_units` must be larger than `min_units`
 37        """
 38        self.name = name
 39        self.min_units = min_units
 40        if max_units == 0 and min_units > 0:
 41            max_units = min_units
 42        self.max_units = max_units
 43        if min_units > max_units:
 44            self.warn(
 45                f"`min_units` is larger than `max_units` for `{self.name}`. This creates an infeasible constraint."
 46            )
 47        self.cashflow_per_unit = cashflow_per_unit
 48
 49        self.cashflow_for_use = cashflow_for_use
 50        if self.cashflow_for_use != 0:
 51            self.use = pulp.LpVariable(name=f"{self.name}_use", cat="Binary")
 52
 53        self.inflows = []
 54        self.outflows = []
 55        self.reflows_in = []
 56        self.reflows_out = []
 57
 58    def sum_flows(self, flow_list: list):
 59        """
 60        Returns the sum of flows in a provided `flow_list` of `Flow` object as a float value.
 61
 62        Requires:
 63
 64        - `flow_list`:
 65            - Type: list
 66            - What: A list of `flow` objects
 67        """
 68        return float(sum([i.flow.value() for i in flow_list]))
 69
 70    def lp_sum_flows(self, flow_list: list):
 71        """
 72        Returns a pulp pulp function to sum of flows in a provided `flow_list` of `Flow` object.
 73
 74        Requires:
 75
 76        - `flow_list`:
 77            - Type: list
 78            - What: A list of flow objects
 79        """
 80        return pulp.lpSum([i.flow for i in flow_list])
 81
 82    def add_constraints(self, model):
 83        """
 84        Updates a provided model with all the constraints needed for this network structure
 85
 86        Requires:
 87
 88        - `model`:
 89            - Type: Model object
 90            - What: The relevant model object that will get the constraints from this network structure
 91        """
 92        # Enforce max unit constraint
 93        model += self.lp_sum_flows(self.outflows) <= self.max_units
 94        model += self.lp_sum_flows(self.outflows) >= self.min_units
 95        # Enforce binary open constraint if cashflow_for_use is not 0
 96        if self.cashflow_for_use != 0:
 97            model += self.lp_sum_flows(self.outflows) <= large_m * self.use
 98
 99    def get_objective_fn(self):
100        """
101        Gets the objective function (in pulp variables) for this network structure
102        """
103        variable_cashflow = self.lp_sum_flows(self.outflows) * self.cashflow_per_unit
104        if self.cashflow_for_use != 0:
105            fixed_cashflow = self.use * self.cashflow_for_use
106        else:
107            fixed_cashflow = 0
108        return variable_cashflow + fixed_cashflow
109
110
111@type_enforced.Enforcer
112class Flow(NetworkStructure):
113    def __init__(
114        self, start: str, end: str, *args, reflow: bool = False, cat: str = "Continuous", **kwargs
115    ):
116        """
117        Extends the NetworkStructure initialization to initialize a new Flow object.
118
119        Requires:
120
121        - `start`:
122            - Type: str
123            - What: The start Node name for this flow
124        - `end`:
125            - Type: str
126            - What: The end Node name for this flow
127
128        Optional:
129
130        - `reflow`:
131            - Type: bool
132            - What: Indicate if this flow is treated as a reflow
133            - Default: False
134            - Note: Reflows do not impact max_units or min_units for attached nodes
135            - Note: Reflows would normally be used to capture the idea of inventory in a multi time period model
136        -  `cat`:
137            - Type: str
138            - What: The type of flow variable to create
139            - Options: ['Continuous','Binary','Integer']
140            - Default: Continuous
141        """
142        super().__init__(*args, **kwargs)
143        self.start = start
144        self.end = end
145        self.flow = pulp.LpVariable(name=f"{self.name}", cat=cat)
146        self.outflows.append(self)
147        self.reflow = reflow
148
149    def add_flows(self, objects: dict):
150        """
151        Adds this flow object to the `start` and `end` nodes for the purpose of calculating node throughput.
152
153        Requires:
154
155        - `objects`:
156            - Type: dict
157            - What: An object dictionary (key=Object.name, Value=Object) for all nodes in the current model
158        """
159        start_entity = objects.get(self.start)
160        if start_entity == None:
161            self.exception(
162                f"`start` entity ({self.start}) not found in current objects list. Did you forget to add it to your nodes? This should be done prior to adding flows. See the `add_nodes` method."
163            )
164        end_entity = objects.get(self.end)
165        if end_entity == None:
166            self.exception(
167                f"`end` entity ({self.end}) not found in current objects list. Did you forget to add it to your nodes? This should be done prior to adding flows. See the `add_nodes` method."
168            )
169        start_entity.add_outflow(self)
170        end_entity.add_inflow(self)
171
172    def get_stats(self):
173        """
174        Get the stats relevant to this flow object
175        """
176        # Dont recalculate stats for this object if it has already been calculated
177        if hasattr(self, "stats"):
178            return self.stats
179        self.stats = {
180            "name": self.name,
181            "class": self.__class__.__name__,
182            "reflow": self.reflow,
183            "start": self.start,
184            "end": self.end,
185            "flow": self.sum_flows(self.outflows),
186            "use": 1.0,
187        }
188        if self.cashflow_for_use != 0:
189            self.stats["use"] = self.use.value()
190        self.stats = {
191            **self.stats,
192            "variable_cashflow": self.stats["flow"] * self.cashflow_per_unit,
193            "fixed_cashflow": self.stats["use"] * self.cashflow_for_use,
194        }
195        return self.stats
196
197
198@type_enforced.Enforcer
199class Node(NetworkStructure):
200    def __init__(self, *args, origin: bool = False, destination: bool = False, **kwargs):
201        """
202        Extends the NetworkStructure initialization process to initialize a new Node object.
203
204        Optional:
205
206        - `origin`:
207            - Type: bool
208            - What: Indicate if this node is an origin
209            - Default: False
210            - Note: Origin nodes do not have a preservation of flow constraint added and new flows be started in them them (from nothingness)
211        - `origin`:
212            - Type: bool
213            - What: Indicate if this node is a destination
214            - Default: False
215            - Note: Destination nodes do not have a preservation of flow constraint added and flows can be terminated in them (into nothingness)
216        """
217        super().__init__(*args, **kwargs)
218        self.origin = origin
219        self.destination = destination
220
221        if origin and destination:
222            self.exception(
223                f"`origin` and `destination` can not both be `true` for any node but are for node `{self.name}`"
224            )
225
226        if self.destination:
227            # Create a link from inflows to outflows to allow general
228            # NetworkStructure class logic to propagate destination nodes
229            self.outflows = self.inflows
230
231    def add_constraints(self, model):
232        """
233        Extends the add_constraints function in NetworkStructure to include preservation of flow to the passed model.
234
235        This only applies if the this node is not an `origin` or `destination` node.
236
237        Preservation of flow fn: `inflows + reflows_in = outflows + reflows_out`
238
239        Requires:
240
241        - `model`:
242            - Type: Model object
243            - What: The relevant model object that will get the constraints from this network structure
244        """
245        super().add_constraints(model)
246        if not (self.origin or self.destination):
247            # Balance Inflows + Reflows_In with Outflows + Reflows_Out
248            model += (self.lp_sum_flows(self.inflows) + self.lp_sum_flows(self.reflows_in)) == (
249                self.lp_sum_flows(self.outflows) + self.lp_sum_flows(self.reflows_out)
250            )
251
252    def add_inflow(self, obj: Flow):
253        """
254        Adds an inflow to this node
255
256        Requires:
257
258        - `obj`:
259            - Type: Flow object
260            - What: A flow that is entering this node
261        """
262        if obj.reflow:
263            self.reflows_in.append(obj)
264        else:
265            self.inflows.append(obj)
266
267    def add_outflow(self, obj: Flow):
268        """
269        Adds an outflow to this node
270
271        Requires:
272
273        - `obj`:
274            - Type: Flow object
275            - What: A flow that is leaving this node
276        """
277        if obj.reflow:
278            self.reflows_out.append(obj)
279        else:
280            self.outflows.append(obj)
281
282    def get_stats(self):
283        """
284        Get the stats relevant to this node object
285        """
286        # Dont recalculate stats for this object if it has already been calculated
287        if hasattr(self, "stats"):
288            return self.stats
289        self.stats = {
290            "name": self.name,
291            "class": self.__class__.__name__,
292            "origin": self.origin,
293            "destination": self.destination,
294            "inflows": self.sum_flows(self.inflows),
295            "outflows": self.sum_flows(self.outflows),
296            "reflows_in": self.sum_flows(self.reflows_in),
297            "reflows_out": self.sum_flows(self.reflows_out),
298            "use": 1.0,
299        }
300        if self.cashflow_for_use != 0:
301            self.stats["use"] = self.use.value()
302        self.stats = {
303            **self.stats,
304            "variable_cashflow": self.stats["outflows"] * self.cashflow_per_unit,
305            "fixed_cashflow": self.stats["use"] * self.cashflow_for_use,
306        }
307        # Fix the special outflows logic post solve to undo the special
308        # logic in self.__init__() above
309        if self.destination:
310            self.stats["outflows"] = 0
311        return self.stats
312
313
314@type_enforced.Enforcer
315class Model(Error):
316    def __init__(self, name: str, objects: [dict, type(None)] = None):
317        """
318        Initialize a new model object to be solved
319
320        Requires:
321
322        - `name`:
323            - Type: str
324            - What: The name of this model object
325
326        Optional:
327
328        - `objects`:
329            - Type: dict
330            - What: A dictionary that contains any pre aggregated `Node`s or `Flow`s.
331            - Note: This should normally only be used for internal testing. Unless you need to custom functionaility, use the Model.add_object function instead of this.
332            - Default: {}
333        """
334        if objects == None:
335            objects = {}
336        self.name = name
337        self.objects = objects
338
339    def solve(self, pulp_log: bool = False, except_on_infeasible: bool = True):
340        """
341        Solve this model given all of the Nodes and Flows
342
343        Optional:
344
345        - `pulp_log`:
346            - Type: bool
347            - What: Indicate if the pulp log should be shown in the terminal
348            - Default: False
349        - `except_on_infeasible`:
350            - Type: bool
351            - What: Indicate if the model should throw an exception if it is infeasible
352            - Note: If False, the model will relax constraints until a solution is found
353            - Default: True
354        """
355        # Create PuLP Model
356        self.model = pulp.LpProblem(name=self.name, sense=pulp.LpMaximize)
357        # Set objective function
358        self.model += pulp.lpSum([i.get_objective_fn() for i in self.objects.values()])
359        # Add constraints
360        [i.add_constraints(self.model) for i in self.objects.values()]
361        # Solve the model
362        self.model.solve(pulp.PULP_CBC_CMD(msg=(3 if pulp_log else 0)))
363
364        if self.model.status == -1:
365            if except_on_infeasible:
366                self.exception("The current model is infeasible and can not be solved.")
367            else:
368                self.warn(
369                    "The current model is infeasible and can not be solved. Constraints have been relaxed to provide a solution anyway."
370                )
371
372        # Parse the objective value
373        self.objective = self.model.objective.value()
374
375    def get_object_stats(self):
376        """
377        Get the statistics for every `Node` and `Flow` in this `Model`.
378        """
379        return {key: value.get_stats() for key, value in self.objects.items()}
380
381    def add_object(self, obj: [Node, Flow]):
382        """
383        Adds a `Node` or `Flow` to this model
384
385        Requires:
386
387        - `obj`:
388            - Type: Flow object | Node object
389            - What: A `Node` or `Flow` to be added to this model
390        """
391        if obj.name in self.objects.keys():
392            self.exception(f"Duplicate name detected: `{obj.name}`")
393        if isinstance(obj, (Flow)):
394            obj.add_flows(self.objects)
395        self.objects[obj.name] = obj