ltbams 0.9.9__py3-none-any.whl → 1.0.0__py3-none-any.whl

ams/opt/constraint.py

@@ -0,0 +1,175 @@
+"""
+Module for optimization Constraint.
+"""
+import logging
+
+from typing import Optional
+import re
+
+import numpy as np
+
+import cvxpy as cp
+
+from ams.utils import pretty_long_message
+from ams.shared import _prefix, _max_length
+
+from ams.opt import OptzBase, ensure_symbols, ensure_mats_and_parsed
+
+logger = logging.getLogger(__name__)
+
+
+class Constraint(OptzBase):
+    """
+    Base class for constraints.
+
+    This class is used as a template for defining constraints. Each
+    instance of this class represents a single constraint.
+
+    Parameters
+    ----------
+    name : str, optional
+        A user-defined name for the constraint.
+    e_str : str, optional
+        A mathematical expression representing the constraint.
+    info : str, optional
+        Additional informational text about the constraint.
+    is_eq : str, optional
+        Flag indicating if the constraint is an equality constraint. False indicates
+        an inequality constraint in the form of `<= 0`.
+
+    Attributes
+    ----------
+    is_disabled : bool
+        Flag indicating if the constraint is disabled, False by default.
+    rtn : ams.routines.Routine
+        The owner routine instance.
+    is_disabled : bool, optional
+        Flag indicating if the constraint is disabled, False by default.
+    code : str, optional
+        The code string for the constraint
+    """
+
+    def __init__(self,
+                 name: Optional[str] = None,
+                 e_str: Optional[str] = None,
+                 info: Optional[str] = None,
+                 is_eq: Optional[bool] = False,
+                 ):
+        OptzBase.__init__(self, name=name, info=info)
+        self.e_str = e_str
+        self.is_eq = is_eq
+        self.is_disabled = False
+        self.code = None
+
+    def get_idx(self):
+        raise NotImplementedError
+
+    def get_all_idxes(self):
+        raise NotImplementedError
+
+    @ensure_symbols
+    def parse(self):
+        """
+        Parse the constraint.
+        """
+        # parse the expression str
+        sub_map = self.om.rtn.syms.sub_map
+        code_constr = self.e_str
+        for pattern, replacement in sub_map.items():
+            try:
+                code_constr = re.sub(pattern, replacement, code_constr)
+            except TypeError as e:
+                raise TypeError(f"Error in parsing constr <{self.name}>.\n{e}")
+        # parse the constraint type
+        code_constr += " == 0" if self.is_eq else " <= 0"
+        # store the parsed expression str code
+        self.code = code_constr
+        msg = f" - Constr <{self.name}>: {self.e_str}"
+        logger.debug(pretty_long_message(msg, _prefix, max_length=_max_length))
+        return True
+
+    def _evaluate_expression(self, code, local_vars=None):
+        """
+        Helper method to evaluate the expression code.
+
+        Parameters
+        ----------
+        code : str
+            The code string representing the expression.
+
+        Returns
+        -------
+        cp.Expression
+            The evaluated cvxpy expression.
+        """
+        return eval(code, {}, local_vars)
+
+    @ensure_mats_and_parsed
+    def evaluate(self):
+        """
+        Evaluate the constraint.
+        """
+        msg = f" - Constr <{self.name}>: {self.code}"
+        logger.debug(pretty_long_message(msg, _prefix, max_length=_max_length))
+        try:
+            local_vars = {'self': self, 'cp': cp, 'sub_map': self.om.rtn.syms.val_map}
+            self.optz = self._evaluate_expression(self.code, local_vars=local_vars)
+        except Exception as e:
+            raise Exception(f"Error in evaluating Constraint <{self.name}>.\n{e}")
+
+    def __repr__(self):
+        enabled = 'OFF' if self.is_disabled else 'ON'
+        out = f"{self.class_name}: {self.name} [{enabled}]"
+        return out
+
+    @property
+    def e(self):
+        """
+        Return the calculated constraint LHS value.
+        Note that `v` should be used primarily as it is obtained
+        from the solver directly.
+
+        `e` is for debugging purpose. For a successfully solved problem,
+        `e` should equal to `v`. However, when a problem is infeasible
+        or unbounded, `e` can be used to check the constraint LHS value.
+        """
+        if self.code is None:
+            logger.info(f"Constraint <{self.name}> is not parsed yet.")
+            return None
+
+        val_map = self.om.rtn.syms.val_map
+        code = self.code
+        for pattern, replacement in val_map.items():
+            try:
+                code = re.sub(pattern, replacement, code)
+            except TypeError as e:
+                raise TypeError(e)
+
+        try:
+            logger.debug(pretty_long_message(f"Value code: {code}",
+                                             _prefix, max_length=_max_length))
+            local_vars = {'self': self, 'np': np, 'cp': cp, 'val_map': val_map}
+            return self._evaluate_expression(code, local_vars)
+        except Exception as e:
+            logger.error(f"Error in calculating constr <{self.name}>.\n{e}")
+            return None
+
+    @property
+    def v(self):
+        """
+        Return the CVXPY constraint LHS value.
+        """
+        if self.optz is None:
+            return None
+        if self.optz._expr.value is None:
+            try:
+                shape = self._expr.shape
+                return np.zeros(shape)
+            except AttributeError:
+                return None
+        else:
+            return self.optz._expr.value
+
+    @v.setter
+    def v(self, value):
+        raise AttributeError("Cannot set the value of the constraint.")

ams/opt/exprcalc.py

@@ -0,0 +1,127 @@
+"""
+Module for optimization ExpressionCalc.
+"""
+import logging
+
+from typing import Optional
+import re
+
+import numpy as np
+
+import cvxpy as cp
+
+from ams.utils import pretty_long_message
+from ams.shared import _prefix, _max_length
+
+from ams.opt import OptzBase, ensure_symbols, ensure_mats_and_parsed
+
+logger = logging.getLogger(__name__)
+
+
+class ExpressionCalc(OptzBase):
+    """
+    Class for calculating expressions.
+
+    Note that `ExpressionCalc` is not a CVXPY expression, and it should not be used
+    in the optimization model.
+    It is used to calculate expression values **after** successful optimization.
+    """
+
+    def __init__(self,
+                 name: Optional[str] = None,
+                 info: Optional[str] = None,
+                 unit: Optional[str] = None,
+                 e_str: Optional[str] = None,
+                 model: Optional[str] = None,
+                 src: Optional[str] = None,
+                 ):
+        OptzBase.__init__(self, name=name, info=info, unit=unit, model=model)
+        self.optz = None
+        self.e_str = e_str
+        self.code = None
+        self.src = src
+
+    @ensure_symbols
+    def parse(self):
+        """
+        Parse the Expression.
+        """
+        # parse the expression str
+        sub_map = self.om.rtn.syms.sub_map
+        code_expr = self.e_str
+        for pattern, replacement in sub_map.items():
+            try:
+                code_expr = re.sub(pattern, replacement, code_expr)
+            except Exception as e:
+                raise Exception(f"Error in parsing expr <{self.name}>.\n{e}")
+        # store the parsed expression str code
+        self.code = code_expr
+        msg = f" - ExpressionCalc <{self.name}>: {self.e_str}"
+        logger.debug(pretty_long_message(msg, _prefix, max_length=_max_length))
+        return True
+
+    @ensure_mats_and_parsed
+    def evaluate(self):
+        """
+        Evaluate the expression.
+        """
+        msg = f" - Expression <{self.name}>: {self.code}"
+        logger.debug(pretty_long_message(msg, _prefix, max_length=_max_length))
+        try:
+            local_vars = {'self': self, 'np': np, 'cp': cp}
+            self.optz = self._evaluate_expression(self.code, local_vars=local_vars)
+        except Exception as e:
+            raise Exception(f"Error in evaluating ExpressionCalc <{self.name}>.\n{e}")
+        return True
+
+    def _evaluate_expression(self, code, local_vars=None):
+        """
+        Helper method to evaluate the expression code.
+
+        Parameters
+        ----------
+        code : str
+            The code string representing the expression.
+
+        Returns
+        -------
+        cp.Expression
+            The evaluated cvxpy expression.
+        """
+        return eval(code, {}, local_vars)
+
+    @property
+    def v(self):
+        """
+        Return the CVXPY expression value.
+        """
+        if self.optz is None:
+            return None
+        else:
+            return self.optz.value
+
+    @property
+    def e(self):
+        """
+        Return the calculated expression value.
+        """
+        if self.code is None:
+            logger.info(f"ExpressionCalc <{self.name}> is not parsed yet.")
+            return None
+
+        val_map = self.om.rtn.syms.val_map
+        code = self.code
+        for pattern, replacement in val_map.items():
+            try:
+                code = re.sub(pattern, replacement, code)
+            except TypeError as e:
+                raise TypeError(e)
+
+        try:
+            logger.debug(pretty_long_message(f"Value code: {code}",
+                                             _prefix, max_length=_max_length))
+            local_vars = {'self': self, 'np': np, 'cp': cp, 'val_map': val_map}
+            return self._evaluate_expression(code, local_vars)
+        except Exception as e:
+            logger.error(f"Error in calculating expr <{self.name}>.\n{e}")
+            return None

ams/opt/expression.py

@@ -0,0 +1,188 @@
+"""
+Module for optimization Expression.
+"""
+import logging
+
+from typing import Optional
+import re
+
+import numpy as np
+
+import cvxpy as cp
+
+from ams.utils import pretty_long_message
+from ams.shared import _prefix, _max_length
+
+from ams.opt import OptzBase, ensure_symbols, ensure_mats_and_parsed
+
+logger = logging.getLogger(__name__)
+
+
+class Expression(OptzBase):
+    """
+    Base class for expressions used in a routine.
+
+    Parameters
+    ----------
+    name : str, optional
+        Expression name. One should typically assigning the name directly because
+        it will be automatically assigned by the model. The value of ``name``
+        will be the symbol name to be used in expressions.
+    tex_name : str, optional
+        LaTeX-formatted variable symbol. Defaults to the value of ``name``.
+    info : str, optional
+        Descriptive information
+    unit : str, optional
+        Unit
+    e_str : str, optional
+        Expression string
+    model : str, optional
+        Name of the owner model or group.
+    src : str, optional
+        Source expression name
+    vtype : type, optional
+        Value type
+    horizon : ams.routines.RParam, optional
+        Horizon
+    """
+
+    def __init__(self,
+                 name: Optional[str] = None,
+                 tex_name: Optional[str] = None,
+                 info: Optional[str] = None,
+                 unit: Optional[str] = None,
+                 e_str: Optional[str] = None,
+                 model: Optional[str] = None,
+                 src: Optional[str] = None,
+                 vtype: Optional[str] = float,
+                 horizon: Optional[str] = None,
+                 ):
+        OptzBase.__init__(self, name=name, info=info, unit=unit, model=model)
+        self.tex_name = tex_name
+        self.e_str = e_str
+        self.optz = None
+        self.code = None
+        self.src = src
+        self.horizon = horizon
+
+    @ensure_symbols
+    def parse(self):
+        """
+        Parse the expression.
+
+        Returns
+        -------
+        bool
+            Returns True if the parsing is successful, False otherwise.
+        """
+        sub_map = self.om.rtn.syms.sub_map
+        code_expr = self.e_str
+        for pattern, replacement in sub_map.items():
+            try:
+                code_expr = re.sub(pattern, replacement, code_expr)
+            except Exception as e:
+                raise Exception(f"Error in parsing expr <{self.name}>.\n{e}")
+        self.code = code_expr
+        msg = f" - Expression <{self.name}>: {self.e_str}"
+        logger.debug(pretty_long_message(msg, _prefix, max_length=_max_length))
+        return True
+
+    @ensure_mats_and_parsed
+    def evaluate(self):
+        """
+        Evaluate the expression.
+
+        Returns
+        -------
+        bool
+            Returns True if the evaluation is successful, False otherwise.
+        """
+        msg = f" - Expression <{self.name}>: {self.code}"
+        logger.debug(pretty_long_message(msg, _prefix, max_length=_max_length))
+        try:
+            local_vars = {'self': self, 'np': np, 'cp': cp, 'sub_map': self.om.rtn.syms.val_map}
+            self.optz = self._evaluate_expression(self.code, local_vars=local_vars)
+        except Exception as e:
+            raise Exception(f"Error in evaluating Expression <{self.name}>.\n{e}")
+        return True
+
+    def _evaluate_expression(self, code, local_vars=None):
+        """
+        Helper method to evaluate the expression code.
+
+        Parameters
+        ----------
+        code : str
+            The code string representing the expression.
+
+        Returns
+        -------
+        cp.Expression
+            The evaluated cvxpy expression.
+        """
+        return eval(code, {}, local_vars)
+
+    @property
+    def v(self):
+        """
+        Return the CVXPY expression value.
+        """
+        if self.optz is None:
+            return None
+        else:
+            return self.optz.value
+
+    @v.setter
+    def v(self, value):
+        """
+        Set the value.
+        """
+        raise NotImplementedError('Cannot set value to an Expression.')
+
+    @property
+    def shape(self):
+        """
+        Return the shape.
+        """
+        try:
+            return self.om.__dict__[self.name].shape
+        except KeyError:
+            logger.warning('Shape info is not ready before initialization.')
+            return None
+
+    @property
+    def size(self):
+        """
+        Return the size.
+        """
+        if self.rtn.initialized:
+            return self.om.__dict__[self.name].size
+        else:
+            logger.warning(f'Routine <{self.rtn.class_name}> is not initialized yet.')
+            return None
+
+    @property
+    def e(self):
+        """
+        Return the calculated expression value.
+        """
+        if self.code is None:
+            logger.info(f"Expression <{self.name}> is not parsed yet.")
+            return None
+
+        val_map = self.om.rtn.syms.val_map
+        code = self.code
+        for pattern, replacement in val_map.items():
+            try:
+                code = re.sub(pattern, replacement, code)
+            except TypeError as e:
+                raise TypeError(e)
+
+        try:
+            logger.debug(pretty_long_message(f"Value code: {code}",
+                                             _prefix, max_length=_max_length))
+            local_vars = {'self': self, 'np': np, 'cp': cp, 'val_map': val_map}
+            return self._evaluate_expression(code, local_vars)
+        except Exception as e:
+            logger.error(f"Error in calculating expr <{self.name}>.\n{e}")
+            return None

ams/opt/objective.py

@@ -0,0 +1,174 @@
+"""
+Module for optimization Objective.
+"""
+import logging
+
+from typing import Optional
+import re
+
+import numpy as np
+
+import cvxpy as cp
+
+from ams.utils import pretty_long_message
+from ams.shared import _prefix, _max_length
+
+from ams.opt import OptzBase, ensure_symbols, ensure_mats_and_parsed
+
+logger = logging.getLogger(__name__)
+
+
+class Objective(OptzBase):
+    """
+    Base class for objective functions.
+
+    This class serves as a template for defining objective functions. Each
+    instance of this class represents a single objective function that can
+    be minimized or maximized depending on the sense ('min' or 'max').
+
+    Parameters
+    ----------
+    name : str, optional
+        A user-defined name for the objective function.
+    e_str : str, optional
+        A mathematical expression representing the objective function.
+    info : str, optional
+        Additional informational text about the objective function.
+    sense : str, optional
+        The sense of the objective function, default to 'min'.
+        `min` for minimization and `max` for maximization.
+
+    Attributes
+    ----------
+    v : NoneType
+        The value of the objective function. It needs to be set through
+        computation.
+    rtn : ams.routines.Routine
+        The owner routine instance.
+    code : str
+        The code string for the objective function.
+    """
+
+    def __init__(self,
+                 name: Optional[str] = None,
+                 e_str: Optional[str] = None,
+                 info: Optional[str] = None,
+                 unit: Optional[str] = None,
+                 sense: Optional[str] = 'min'):
+        OptzBase.__init__(self, name=name, info=info, unit=unit)
+        self.e_str = e_str
+        self.sense = sense
+        self.code = None
+
+    @property
+    def e(self):
+        """
+        Return the calculated objective value.
+
+        Note that `v` should be used primarily as it is obtained
+        from the solver directly.
+
+        `e` is for debugging purpose. For a successfully solved problem,
+        `e` should equal to `v`. However, when a problem is infeasible
+        or unbounded, `e` can be used to check the objective value.
+        """
+        if self.code is None:
+            logger.info(f"Objective <{self.name}> is not parsed yet.")
+            return None
+
+        val_map = self.om.rtn.syms.val_map
+        code = self.code
+        for pattern, replacement in val_map.items():
+            try:
+                code = re.sub(pattern, replacement, code)
+            except TypeError as e:
+                logger.error(f"Error in parsing value for obj <{self.name}>.")
+                raise e
+
+        try:
+            logger.debug(pretty_long_message(f"Value code: {code}",
+                                             _prefix, max_length=_max_length))
+            local_vars = {'self': self, 'np': np, 'cp': cp, 'val_map': val_map}
+            return self._evaluate_expression(code, local_vars)
+        except Exception as e:
+            logger.error(f"Error in calculating obj <{self.name}>.\n{e}")
+            return None
+
+    @property
+    def v(self):
+        """
+        Return the CVXPY objective value.
+        """
+        if self.optz is None:
+            return None
+        else:
+            return self.optz.value
+
+    @v.setter
+    def v(self, value):
+        raise AttributeError("Cannot set the value of the objective function.")
+
+    @ensure_symbols
+    def parse(self):
+        """
+        Parse the objective function.
+
+        Returns
+        -------
+        bool
+            Returns True if the parsing is successful, False otherwise.
+        """
+        # parse the expression str
+        sub_map = self.om.rtn.syms.sub_map
+        code_obj = self.e_str
+        for pattern, replacement, in sub_map.items():
+            try:
+                code_obj = re.sub(pattern, replacement, code_obj)
+            except Exception as e:
+                raise Exception(f"Error in parsing obj <{self.name}>.\n{e}")
+        # store the parsed expression str code
+        self.code = code_obj
+        if self.sense not in ['min', 'max']:
+            raise ValueError(f'Objective sense {self.sense} is not supported.')
+        sense = 'cp.Minimize' if self.sense == 'min' else 'cp.Maximize'
+        self.code = f"{sense}({code_obj})"
+        msg = f" - Objective <{self.name}>: {self.code}"
+        logger.debug(pretty_long_message(msg, _prefix, max_length=_max_length))
+        return True
+
+    @ensure_mats_and_parsed
+    def evaluate(self):
+        """
+        Evaluate the objective function.
+
+        Returns
+        -------
+        bool
+            Returns True if the evaluation is successful, False otherwise.
+        """
+        logger.debug(f" - Objective <{self.name}>: {self.e_str}")
+        try:
+            local_vars = {'self': self, 'cp': cp}
+            self.optz = self._evaluate_expression(self.code, local_vars=local_vars)
+        except Exception as e:
+            raise Exception(f"Error in evaluating Objective <{self.name}>.\n{e}")
+        return True
+
+    def _evaluate_expression(self, code, local_vars=None):
+        """
+        Helper method to evaluate the expression code.
+
+        Parameters
+        ----------
+        code : str
+            The code string representing the expression.
+
+        Returns
+        -------
+        cp.Expression
+            The evaluated cvxpy expression.
+        """
+        return eval(code, {}, local_vars)
+
+    def __repr__(self):
+        return f"{self.class_name}: {self.name} [{self.sense.upper()}]"