V3.1

Author: willgebhardt

ngcsimlib/__init__.py

@@ -1,75 +1,5 @@
-from . import utils
+from ngcsimlib._src.component import Component as Component
+from ngcsimlib._src.process import Process
 
-import argparse, os, json
-from types import SimpleNamespace
-from importlib import import_module
-from ngcsimlib.configManager import init_config, get_config
-from ngcsimlib.logger import warn
-from pkg_resources import get_distribution
+import ngcsimlib.operations
 
-__version__ = get_distribution('ngcsimlib').version  ## set software version
-
-
-###### Preload Modules
-def preload_modules(path=None):
-    if path is None:
-        module_config = get_config("modules")
-        if module_config is None:
-            module_path = None
-        else:
-            module_path = module_config.get("module_path", None)
-
-        if module_path is None:
-            return
-
-        if not os.path.isfile(module_path):
-            warn("Missing file to preload modules from. Attempted to locate file at \"" + str(module_path) +
-                          "\". No modules will be preloaded. "
-                          "\nSee https://ngc-learn.readthedocs.io/en/latest/tutorials/model_basics/json_modules.html for additional information")
-            return
-    else:
-        module_path = path
-
-    with open(module_path, 'r') as file:
-        modules = json.load(file, object_hook=lambda d: SimpleNamespace(**d))
-
-    for module in modules:
-        load_module(module)
-
-def load_module(module):
-    mod = import_module(module.absolute_path)
-    utils.modules._Loaded_Modules[module.absolute_path] = mod
-
-    for attribute in module.attributes:
-        atr = getattr(mod, attribute.name)
-        utils.modules._Loaded_Attributes[attribute.name] = atr
-
-        utils.modules._Loaded_Attributes[
-            ".".join([module.absolute_path, attribute.name])] = atr
-        if hasattr(attribute, "keywords"):
-            for keyword in attribute.keywords:
-                utils.modules._Loaded_Attributes[keyword] = atr
-
-###### Initialize Config
-def configure():
-    parser = argparse.ArgumentParser(description='Build and run a model using ngclearn')
-    parser.add_argument("--config", type=str, help='location of config.json file')
-
-    ## ngc-sim-lib only cares about --config argument
-    args, unknown = parser.parse_known_args()  # args = parser.parse_args()
-    try:
-        config_path = args.modules
-    except:
-        config_path = None
-
-    if config_path is None:
-        config_path = "json_files/config.json"
-
-    if not os.path.isfile(config_path):
-        warn("Missing configuration file. Attempted to locate file at \"" + str(config_path) +
-                      "\". Default Config will be used. "
-                      "\nSee https://ngc-learn.readthedocs.io/en/latest/tutorials/model_basics/configuration.html for "
-                      "additional information")
-        return
-
-    init_config(config_path)

ngcsimlib/_src/__init__.py

@@ -0,0 +1,75 @@
+# from . import utils
+#
+# import argparse, os, json
+# from types import SimpleNamespace
+# from importlib import import_module
+# from ngcsimlib.configManager import init_config, get_config
+# from ngcsimlib.logger import warn
+# from pkg_resources import get_distribution
+#
+# __version__ = get_distribution('ngcsimlib').version  ## set software version
+#
+#
+# ###### Preload Modules
+# def preload_modules(path=None):
+#     if path is None:
+#         module_config = get_config("modules")
+#         if module_config is None:
+#             module_path = None
+#         else:
+#             module_path = module_config.get("module_path", None)
+#
+#         if module_path is None:
+#             return
+#
+#         if not os.path.isfile(module_path):
+#             warn("Missing file to preload modules from. Attempted to locate file at \"" + str(module_path) +
+#                           "\". No modules will be preloaded. "
+#                           "\nSee https://ngc-learn.readthedocs.io/en/latest/tutorials/model_basics/json_modules.html for additional information")
+#             return
+#     else:
+#         module_path = path
+#
+#     with open(module_path, 'r') as file:
+#         modules = json.load(file, object_hook=lambda d: SimpleNamespace(**d))
+#
+#     for module in modules:
+#         load_module(module)
+#
+# def load_module(module):
+#     mod = import_module(module.absolute_path)
+#     utils.modules._Loaded_Modules[module.absolute_path] = mod
+#
+#     for attribute in module.attributes:
+#         atr = getattr(mod, attribute.name)
+#         utils.modules._Loaded_Attributes[attribute.name] = atr
+#
+#         utils.modules._Loaded_Attributes[
+#             ".".join([module.absolute_path, attribute.name])] = atr
+#         if hasattr(attribute, "keywords"):
+#             for keyword in attribute.keywords:
+#                 utils.modules._Loaded_Attributes[keyword] = atr
+#
+# ###### Initialize Config
+# def configure():
+#     parser = argparse.ArgumentParser(description='Build and run a model using ngclearn')
+#     parser.add_argument("--config", type=str, help='location of config.json file')
+#
+#     ## ngc-sim-lib only cares about --config argument
+#     args, unknown = parser.parse_known_args()  # args = parser.parse_args()
+#     try:
+#         config_path = args.modules
+#     except:
+#         config_path = None
+#
+#     if config_path is None:
+#         config_path = "json_files/config.json"
+#
+#     if not os.path.isfile(config_path):
+#         warn("Missing configuration file. Attempted to locate file at \"" + str(config_path) +
+#                       "\". Default Config will be used. "
+#                       "\nSee https://ngc-learn.readthedocs.io/en/latest/tutorials/model_basics/configuration.html for "
+#                       "additional information")
+#         return
+#
+#     init_config(config_path)

ngcsimlib/_src/compartment/__init__.py

@@ -0,0 +1 @@
+from .compartment import Compartment as Compartment

ngcsimlib/_src/compartment/compartment.py

@@ -0,0 +1,145 @@
+from .compartmentMeta import CompartmentMeta
+from ngcsimlib._src.global_state.manager import global_state_manager as gState
+from ngcsimlib._src.logger import warn
+import ast
+from typing import TypeVar, Union
+from ngcsimlib._src.operations.BaseOp import BaseOp
+from ngcsimlib._src.context.context_manager import global_context_manager as gcm
+
+T = TypeVar('T')
+
+class Compartment(metaclass=CompartmentMeta):
+    """
+    Compartments exist as a layer between the global state of models and the
+    use defined objects. At their core they function akin to pointers where
+    each compartment stores a key that can be used to access a value in the
+    global state. If another compartment is wired into a compartment only the
+    target the compartment is pointing to changes, as such their build value in
+    the global state will no longer change (it will still exist but just
+    nothing will access it unless the user manually goes looking for it). The
+    compartment should be reflected in the global state immediately after it is
+    initialized. Compartments can be flagged as fixed which means that they
+    exist in the global state and can be used in compiled methods but they can
+    not be changed after creation.
+
+    Args
+        initial_value: the initial value to set in the global state
+
+        fixed (default=False): sets the flag for if this compartment is fixed.
+    """
+    def __init__(self, initial_value: T, fixed: bool = False):
+        self._initial_value = initial_value
+
+        self.name = None
+        self._root_target = None
+        self._target = self._root_target
+        self._fixed = fixed
+
+    @property
+    def root(self):
+        return self._root_target
+
+    @property
+    def targeted(self) -> bool:
+        return self._target != self._root_target
+
+    @property
+    def fixed(self) -> bool:
+        """
+        Returns: if this compartment is a fixed value.
+        """
+        return self._fixed
+
+    def _setup(self, objName, compName, path):
+        self.name = compName
+        self._root_target = path + ":" + objName + ":" + self.name
+        self._target = self._root_target
+        self.set(self._initial_value)
+        gState.add_compartment(self)
+
+    def set(self, value: T) -> None:
+        """
+        Sets the value that this compartment is pointing to in the global state.
+        This method will abort if either the compartment is flagged as fixed or
+        the compartment is not pointing to the compartment assigned to it. This
+        would be the case if something was wired into this compartment.
+
+        Args:
+            value: The value to set in the global state.
+        """
+        if self._fixed:
+            warn(f"Attempting to set {self._root_target} which is a fixed compartment. Aborting!")
+            return
+        if self.target != self._root_target:
+            warn(f"Attempting to set {self.target} in {self._root_target}. Aborting!")
+            return
+        gState.set_state({self.target: value})
+
+    def get(self) -> T:
+        """
+        Returns: The value that this compartment is pointing to in the global state.
+        """
+        return self._get_value()
+
+    def get_needed_keys(self):
+        if isinstance(self.target, BaseOp):
+            return self.target.get_needed_keys()
+        return set(self.target)
+
+    def _get_value(self):
+        if isinstance(self.target, BaseOp):
+            return self.target.get()
+
+        return gState.from_global_key(self.target)
+
+    def __jax_array__(self):
+        return self.get()
+
+    def __str__(self):
+        return str(self._get_value())
+
+    def _to_ast(self, node, ctx):
+        if isinstance(self.target, str):
+            return ast.Subscript(
+                value=ast.Name(id=ctx, ctx=ast.Load()),
+                slice=ast.Constant(value=self.target),
+                ctx=node.ctx
+            )
+        return self.target._to_ast(node, ctx)
+
+    def __rrshift__(self, other):
+        gcm.current_context.add_connection(other, self)
+        self.target = other
+
+    def __rshift__(self, other):
+        if isinstance(other, Compartment):
+            other.__rrshift__(self)
+
+    @property
+    def target(self):
+        """
+        Returns: the current target of the compartment
+        """
+        return self._target
+
+    @target.setter
+    def target(self, value: Union["Compartment", "BaseOp", str]):
+        """
+        Sets the target of the compartment to the provided value. It will fail
+        if the value is not either another compartment or an operation.
+
+        Args:
+            value: The value to target this compartment at.
+        """
+        if isinstance(value, (str, BaseOp)):
+            self._target = value
+            return
+
+        if isinstance(value, Compartment):
+            self._target = value.target
+            return
+
+        if isinstance(value, str):
+            self._target = value
+
+        raise ValueError("Invalid compartment target ", value)

ngcsimlib/compartment/compartmentMeta.py …mlib/_src/compartment/compartmentMeta.pyngcsimlib/compartment/compartmentMeta.py renamed to ngcsimlib/_src/compartment/compartmentMeta.py ngcsimlib/compartment/compartmentMeta.py renamed to ngcsimlib/_src/compartment/compartmentMeta.py

@@ -1,7 +1,8 @@
 import operator
-import types
+from typing import Any
 
-def _unwrap(x):
+
+def _unwrap(x: Any) -> Any:
     while hasattr(x, "_get_value"):
         x = x._get_value()
     return x
@@ -16,8 +17,6 @@ def _unwrap(x):
     '__floordiv__': operator.floordiv,
     '__mod__': operator.mod,
     '__pow__': operator.pow,
-    '__lshift__': operator.lshift,
-    '__rshift__': operator.rshift,
     '__and__': operator.and_,
     '__xor__': operator.xor,
     '__or__': operator.or_,
@@ -29,9 +28,15 @@ def _unwrap(x):
     '__ge__': operator.ge,
 }
 
-_REVERSE_OPS = {f"__r{name[2:]}__": op for name, op in _BINARY_OPS.items()}
+_REVERSE_OPS = {f"__r{name[2:]}": op for name, op in _BINARY_OPS.items()}
 
 class CompartmentMeta(type):
+    """
+    This is the metaclass for compartments. It mostly exists to sit on top of
+    objects that can be used as targets for compartments. It is rare that users
+    of ngclearn will need to interface with this directly. If you are here
+    trying to learn about compartments look at their file directly.
+    """
     def __new__(mcs, name, bases, namespace):
         def make_op(opfunc):
             def method(self, other):
@@ -45,5 +50,4 @@ def method(self, other):
         for dunder_name, opfunc in _REVERSE_OPS.items():
             if dunder_name not in namespace:
                 namespace[dunder_name] = make_op(opfunc)
-
         return super().__new__(mcs, name, bases, namespace)

ngcsimlib/_src/component.py

@@ -0,0 +1,26 @@
+from ngcsimlib._src.context.contextAwareObject import ContextAwareObject
+from ngcsimlib._src.context.contextObjectDecorators import component
+from ngcsimlib._src.compartment.compartment import Compartment
+from ngcsimlib._src.parser.utils import compilable
+from typing import List, Tuple, Dict, Any
+
+
+@component
+@compilable
+class Component(ContextAwareObject):
+    """
+    Component is a base class of context aware objects that are also specially
+    tracked by contexts. They are expected to make up a large amount of
+    user-defined classes as they will be the various parts of models.
+    """
+    def __init__(self, name):
+        super().__init__(name)
+
+    @property
+    def compartments(self) -> List[Tuple[str, Compartment]]:
+        """
+        It is expected that components will have compartments, and this allows
+        for easy iteration over all the compartments in a component.
+        Returns: a list of compartments found on this component
+        """
+        return [(n, v) for n, v in vars(self).items() if isinstance(v, Compartment)]

ngcsimlib/configManager.py ngcsimlib/_src/configManager.pyngcsimlib/configManager.py renamed to ngcsimlib/_src/configManager.py

@@ -0,0 +1,10 @@
+from .contextAwareObject import ContextAwareObject
+
+from .context import Context as Context # Needs to be after ContextAwareObject
+from .context import ContextObjectTypes as ContextObjectTypes
+
+from .context_manager import global_context_manager as global_context_manager
+from .contextObjectDecorators import (
+    component as component,
+    process as process
+)