engforge 0.3.0__py3-none-any.whl

engforge/system.py

@@ -0,0 +1,143 @@
+"""A System is a Configuration that orchestrates dataflow between components, as well as solving systems of equations in the presense of limits, as well as formatting results of each Component into reporting ready dataframe. System's solver behavior is inspired by NASA's numerical propulsion simulation system (NPSS) to solve systems of inequalities in complex systems.
+
+Component or other subsystems are added to a System class with `Slots`:
+    ```
+    class CustomSystem(System):
+        slot_name = Slot.define(Component,ComponentSubclass,System)
+    ```
+
+Component's data flow is established via `SignalS` that are defined:
+    ```
+    class CustomSystem(System):
+        signal_name = Signal.define(source_attr_or_property, target_attr)
+        control_signal = Signal.define(source_attr_or_property, target_attr,control_with='system.attr or slot.attr`)
+    ```
+    - source_attr: can reference a locally defined slot attribute (a la attr's fields) or any locally defined slot system property
+    - target_attr: must be a locally defined slot attribute or system attribute.
+
+update description to include solver
+
+A system calculates its state upon calling `System.run()`. This executes `pre_execute()` first which will directly update any attributes based on their `Signal` definition between `Slot` components. Once convergence is reached target_attr's are updated in `post_execute()` for cyclic SignalS.
+
+If the system encounters a subsystem in its solver routine, the subsystem is evald() and its results used as static in that iteration,ie it isn't included in the system level dependents if cyclic references are found.
+
+
+The solver uses the root or cobla scipy optimizer results on quick references to internal component references. Upon solving the system
+
+SignalS can be limited with constrains via `min or max` values on `NumericProperty` which can be numeric values (int or float) or functions taking one argument of the component it is defined on. Additionally signals may take arguments of `min` or `max` which are numeric values or callbacks which take the system instance as an argument.
+"""
+
+import attrs
+
+from engforge.properties import *
+from engforge.logging import LoggingMixin
+from engforge.configuration import Configuration, forge
+from engforge.components import SolveableInterface
+from engforge.solver import SolverMixin
+from engforge.attr_plotting import PlottingMixin
+from engforge.dynamics import GlobalDynamics
+
+import copy
+import collections
+import typing
+import numpy
+
+
+# make a module logger
+class SystemsLog(LoggingMixin):
+    pass
+
+
+log = SystemsLog()
+
+
+# NOTE: solver must come before solvable interface since it overrides certain methods
+@forge
+class System(SolverMixin, SolveableInterface, PlottingMixin, GlobalDynamics):
+    """A system defines SlotS for Components, and data flow between them using SignalS
+
+    The system records all attribues to its subcomponents via system_references with scoped keys to references to set or get attributes, as well as observe system properties. These are cached upon first access in an instance.
+
+    The table is made up of these system references, allowing low overhead recording of systems with many variables.
+
+    When solving by default the run(revert=True) call will revert the system state to what it was before the system began.
+    """
+
+    # default to nothing
+    dynamic_input_vars: list = attrs.field(factory=list)
+    dynamic_state_vars: list = attrs.field(factory=list)
+    dynamic_output_vars: list = attrs.field(factory=list)
+
+    _anything_changed_ = True
+    _solver_override: bool = (
+        False  # this comp will run with run_internal_systems when True, otherwise it resolves to global solver behavior, also prevents the solver from reaching into this system
+    )
+
+    # Properties!
+    @system_property
+    def converged(self) -> int:
+        if self.last_context is None:
+            return None
+        return self.last_context.converged
+
+    @property
+    def _converged(self):
+        return self.last_context.converged
+
+    @_converged.setter
+    def _converged(self, inpt):
+        self.last_context._converged = inpt
+
+    @system_property
+    def run_id(self) -> int:
+        if self.last_context is None:
+            return None
+        return self.last_context.problem_id
+
+    @classmethod
+    def subclasses(cls, out=None):
+        """
+        return all subclasses of components, including their subclasses
+        :param out: out is to pass when the middle of a recursive operation, do not use it!
+        """
+
+        # init the set by default
+        if out is None:
+            out = set()
+
+        for cls in cls.__subclasses__():
+            out.add(cls)
+            cls.subclasses(out)
+
+        return out
+
+    def clone(self):
+        """returns a clone of this system, often used to iterate the system without affecting the input values at the last convergence step."""
+        return copy.deepcopy(self)
+
+    @property
+    def identity(self):
+        if self.run_id:
+            return f"{self.name}_{self.run_id}"
+        else:
+            return f"{self.name}"
+
+    @property
+    def _anything_changed(self):
+        """looks at internal components as well as flag for anything chagned."""
+        if self._anything_changed_:
+            return True
+        elif any([c.anything_changed for k, c in self.comp_references().items()]):
+            return True
+        return False
+
+    @_anything_changed.setter
+    def _anything_changed(self, inpt):
+        """allows default functionality with new property system"""
+        self.mark_all_comps_changed(inpt)
+
+    def mark_all_comps_changed(self, inpt: bool):
+        """mark all components as changed, useful for forcing a re-run of the system, or for marking data as saved"""
+        self._anything_changed_ = inpt
+        for k, c in self.comp_references().items():
+            c._anything_changed = inpt

engforge/system_reference.py

@@ -0,0 +1,299 @@
+"""Module to define the Ref class and utility methods for working with it.
+
+Ref's are designed to create adhoc links between the systems & components of the system, and their properties. This is useful for creating optimization problems, and for creating dynamic links between the state and properties of the system. Care must be used on the component objects changing of state, the recommened procedure is to copy your base system to prevent hysterisis and other issues, then push/pop X values through the optimization methods and change state upon success
+
+Ref.component can be a Component,System or dictionary for referencing via keyword. Ref.key can be a string or a callable, if callable the ref will be evaluated as the result of the callable (allow_set=False), this renders the component unused, and disables the ability to set the value of the reference.
+"""
+
+import attrs
+import inspect
+import numpy as np
+import collections
+import scipy.optimize as sciopt
+from contextlib import contextmanager
+from engforge.properties import *
+import copy
+from difflib import get_close_matches
+
+
+class RefLog(LoggingMixin):
+    pass
+
+
+log = RefLog()
+
+
+def refset_input(refs, delta_dict, chk=True, fail=True, warn=True, scope="ref"):
+    """change a set of refs with a dictionary of values. If chk is True k will be checked for membership in refs"""
+    keys = set(refs.keys())
+    for k, v in delta_dict.items():
+        if isinstance(k, Ref):
+            k.set_value(v)
+            continue
+
+        memb = k in refs
+        # if a match or not checking go ahead.
+        if not chk or memb:
+            refs[k].set_value(v)
+
+        # TODO: handle setting non-ref values such as dictionaries
+
+        elif fail and chk and not memb:
+            close = get_close_matches(k, keys)
+            raise KeyError(f"{scope}| key {k} not in refs. did you mean {close}?")
+        elif warn and chk and not memb:
+            close = get_close_matches(k, keys)
+            log.warning(f"{scope}| key {k} not in refs. did you mean {close}")
+
+
+def refset_get(refs, *args, **kw):
+    out = {}
+    scope = kw.get("scope", "ref")
+    for k in refs:
+        try:
+            # print(k,refs[k])
+            out[k] = refs[k].value(refs[k].comp, **kw)
+        except Exception as e:
+            rf = refs[k]
+            log.error(e, f"{scope}| issue with ref: {rf}|{rf.key}|{rf.comp}")
+
+    return out
+
+
+# def f_root(ResRef: collections.OrderedDict, norm: dict = None):
+#     residual = [v.value() / (norm[k] if norm else 1) for k, v in ResRef.items()]
+#     res = np.array(residual)
+#     return res
+#
+#
+# def f_min(ResRef: collections.OrderedDict, norm: dict = None):
+#     res = [v.value() / (norm[k] if norm else 1) for k, v in ResRef.items()]
+#     ans = np.linalg.norm(res, 2)
+#
+#     if ans < 1:
+#         return ans**0.5
+#     return ans
+
+
+def eval_ref(canidate, *args, **kw):
+    # print(f'eval_ref {canidate,args,kw}')
+    if isinstance(canidate, Ref):
+        return canidate.value(*args, **kw)
+    elif callable(canidate):
+        o = canidate(*args, **kw)
+        return o
+    return canidate
+
+
+def scale_val(val, mult=None, bias=None, power=None) -> float:
+    if any((mult, bias, power)):
+        if power is not None:
+            val = val**power
+        if mult is not None:
+            val = mult * val
+        if bias is not None:
+            val = bias + val
+    return val
+
+
+def maybe_ref(can, astype=None, mult=None, bias=None, power=None, *args, **kw):
+    """returns the value of a ref if it is a ref, otherwise returns the value"""
+    # print(f'maybe  {can,astype}')
+    # print(can,astype,mult,bias,power,args,kw)
+    if isinstance(can, Ref):
+        val = can.value(*args, **kw)
+        return scale_val(val, mult, bias, power)
+    elif astype and isinstance(can, astype):
+        ref = can.as_ref_dict()  # TODO: optimize this
+        return scale_val(ref.value(*args, **kw), mult, bias, power)
+    return can
+
+
+def maybe_attr_inst(can, astype=None):
+    """returns the ref if is one otherwise convert it, otherwise returns the value"""
+    if isinstance(can, Ref):
+        return can
+    elif astype and isinstance(can, astype):
+        return astype.backref.handle_instance(can)
+    return can
+
+
+# Important State Preservation
+# TODO: check for hidden X dependents / circular references ect.
+# TODO: make global storage for Ref's based on the comp,key pair. This
+class Ref:
+    """A way to create portable references to system's and their component's properties, ref can also take a key to a zero argument function which will be evald. This is useful for creating an adhoc optimization problems dynamically between variables. However use must be carefully controlled to avoid circular references, and understanding the safe use of the refset_input and refset_get methods (changing state on actual system).
+
+    A dictionary can be used as a component, and the key will be used to access the value in the dictionary.
+
+    The key can be a callable of (*args,**kw) only in which case Ref.value(*args,**kw) will take input, and the ref will be evaluated as the result of the callable (allow_set=False), this renders the component unused, and disables the ability to set the value of the reference.
+
+    The ability to set this ref with another on key input allows for creating a reference that is identical to another reference except for the component provided if it is not None.
+    """
+
+    __slots__ = [
+        "comp",
+        "key",
+        "use_call",
+        "use_dict",
+        "allow_set",
+        "eval_f",
+        "key_override",
+        "_value_eval",
+        "_log_func",
+        "hxd",
+        "_name",
+        "attr_type",
+    ]
+    comp: "TabulationMixin"
+    key: str
+    use_call: bool
+    use_dict: bool
+    allow_set: bool
+    eval_f: callable
+    key_override: bool
+    _value_eval: callable
+    _log_func: callable
+    attr_type: type
+
+    def __init__(self, comp, key, use_call=True, allow_set=True, eval_f=None):
+        self.set(comp, key, use_call, allow_set, eval_f)
+
+    def set(self, comp, key, use_call=True, allow_set=True, eval_f=None):
+        # key can be a ref, in which case this ref will be identical to the other ref except for the component provided if it is not None
+        from engforge.engforge_attributes import AttributedBaseMixin
+
+        if isinstance(key, Ref):
+            self.__dict__.update(key.__dict__)
+            if comp is not None:
+                self.comp = comp
+            return  # a monkey patch
+
+        self.comp = comp
+        if isinstance(self.comp, dict):
+            self.use_dict = True
+            self._name = "dict"
+        else:
+            self.use_dict = False
+
+        self.key_override = False
+        if callable(key):
+            self.key_override = True
+            self.key = key  # this should take have signature f(system,slv_info)
+            self.use_call = False
+            self.allow_set = False
+            self.eval_f = eval_f
+            self._name = "callable"
+        else:
+            self.key = key
+            self.use_call = use_call
+            self.allow_set = allow_set
+            self.eval_f = eval_f
+            if not self.use_dict:
+                self._name = self.comp.classname
+
+        self.attr_type = None
+        if self.allow_set and isinstance(self.comp, AttributedBaseMixin):
+            fieldz = self.comp.__class__.cls_all_attrs_fields()
+            atr_canidate = fieldz.get(self.key, None)
+            if isinstance(atr_canidate, attrs.Attribute):
+                self.attr_type = atr_canidate.type
+
+        if not hasattr(self, "_name"):
+            self._name = "NULL"
+
+        self.hxd = str(hex(id(self)))[-6:]
+
+        # TODO: update with change (pyee?)
+        self.setup_calls()
+
+    def setup_calls(self):
+        """caches anonymous functions for value and logging speedup"""
+        if (
+            self.comp
+            and isinstance(self.comp, LoggingMixin)
+            and self.comp.log_level <= 2
+        ):
+            self._log_func = lambda val: self.comp.msg(
+                f"REF[get] {str(self):<50} -> {val}"
+            )
+        else:
+            self._log_func = None
+
+        if self.key_override:
+            self._value_eval = lambda *a, **kw: self.key(*a, **kw)
+        else:
+            # do not cross reference vars!
+            # TODO: allo for comp/key changes with events
+            if self.key == "":  # return the component
+                p = lambda *a, **kw: self.comp
+            elif self.use_dict:
+                p = lambda *a, **kw: self.comp.get(self.key)
+            elif self.key in self.comp.__dict__:
+                p = lambda *a, **kw: self.comp.__dict__[self.key]
+            else:
+                p = lambda *a, **kw: getattr(self.comp, self.key)
+
+            if self.eval_f:
+                g = lambda *a, **kw: self.eval_f(p(*a, **kw))
+            else:
+                g = p
+
+            self._value_eval = g
+
+    def copy(self, **changes):
+        """copy the reference, and make changes to the copy"""
+        if "key" not in changes:
+            changes["key"] = self.key
+        if "comp" not in changes:
+            changes["comp"] = self.comp
+        cy = copy.copy(self)
+        cy.set(**changes)
+        return cy
+
+    def value(self, *args, **kw):
+        if log.log_level <= 10:
+            try:
+                o = self._value_eval(*args, **kw)
+                if self._log_func:
+                    self._log_func(o)
+                return o
+            except Exception as e:
+                log.error(e, f"issue with ref: {self}|{self.key}|{self.comp}")
+        else:
+            o = self._value_eval(*args, **kw)
+            if self._log_func:
+                self._log_func(o)
+            return o
+
+    def set_value(self, val):
+        if self.allow_set:
+            if self.attr_type not in (str, float, int, bool):
+                if self.comp and self.comp.log_level < 10:
+                    self.comp.msg(f"REF[set] {self} <- {val}")
+                return setattr(self.comp, self.key, val)
+            elif self.value() != val:  # this increases perf. by reducing writes
+                if self.comp and self.comp.log_level < 10:
+                    self.comp.msg(f"REF[set] {self} <- {val}")
+                return setattr(self.comp, self.key, val)
+        else:
+            raise Exception(f"not allowed to set value on {self.key}")
+
+    @property
+    def full_key(self):
+        if self.key_override:
+            return f"{self._name}.{self.key.__name__}"
+        else:
+            return f"{self._name}.{self.key}"
+
+    def __str__(self) -> str:
+        if self.use_dict:
+            return f"REF[{self.hxd}][DICT.{self.key}]"
+        return f"REF[{self.hxd}][{self.full_key}]"
+
+    def __repr__(self) -> str:
+        return f"REF[{self.hxd}][{self.full_key}]"
+
+    # Utilty Methods
+    refset_get = refset_get
+    refset_input = refset_input