ngcsimlib 0.2b0__py3-none-any.whl

ngcsimlib/__init__.py

@@ -0,0 +1,50 @@
+from . import utils
+from . import controller
+from . import commands
+
+import argparse, os, warnings, json
+from types import SimpleNamespace
+from pathlib import Path
+from sys import argv
+from importlib import import_module
+
+from pkg_resources import get_distribution
+
+__version__ = get_distribution('ngcsimlib').version ## set software version
+
+###### Preload Modules
+def preload():
+    parser = argparse.ArgumentParser(description='Build and run a model using ngclearn')
+    parser.add_argument("--modules", type=str, help='location of modules.json file')
+
+    args = parser.parse_args()
+    try:
+        module_path = args.modules
+    except:
+        module_path = None
+
+    if module_path is None:
+        module_path = "json_files/modules.json"
+
+    if not os.path.isfile(module_path):
+        warnings.warn("Missing file to preload modules from. Attempted to locate file at \"" + str(module_path) + "\"" )
+        return
+
+    with open(module_path, 'r') as file:
+        modules = json.load(file, object_hook=lambda d: SimpleNamespace(**d))
+
+    for module in modules:
+        mod = import_module(module.absolute_path)
+        utils._Loaded_Modules[module.absolute_path] = mod
+
+        for attribute in module.attributes:
+            atr = getattr(mod, attribute.name)
+            utils._Loaded_Attributes[attribute.name] = atr
+
+            utils._Loaded_Attributes[".".join([module.absolute_path, attribute.name])] = atr
+            if hasattr(attribute, "keywords"):
+                for keyword in attribute.keywords:
+                    utils._Loaded_Attributes[keyword] = atr
+
+if not Path(argv[0]).name == "sphinx-build" or Path(argv[0]).name == "build.py":
+    preload()

ngcsimlib/bundle_rules.py

@@ -0,0 +1,64 @@
+"""
+Contains all the built-in bundle rules as well as the default one for an unbundled
+cable. Bundle(s) usage is that it is to be added to a component's bundle rules
+(Note: the overwrite rule is the default rule).
+
+
+Template for bundle rules. The name of the bundle rule should be meaningful to what it does. All bundle rules will
+be called with the same three inputs: component, value, and destination_compartment. These are not passed by keyword but
+they will always be in the same order. The component is the component that the bundle has as a destination (target).
+The value is the signal that goes into (or comes along to) the connected bundle. The destination_compartment is
+the compartment that the bundle is connected to. Overall, the general usage of bundle rules is to modify the
+behavior of an input to a compartment; generally, they should NOT modify any other aspect of the target
+component aside from the destination compartment and, as a warning, should not try to reference compartments by
+name as this will possibly result in runtime errors given that the required compartments for the bundle rule(s)
+might not exist.
+
+General bundle rule specification:
+
+def BUNDLE_RULE_NAME(component, value, destination_compartment):
+    ## Logic for processing transmitted value
+    ## Syntax for referencing destination compartment -> component.compartments[destination_compartment]
+
+"""
+def overwrite(component, value, destination_compartment):
+    """
+    The overwrite bundle rule routine.
+
+    Args:
+        component: target component node that this bundle rule will operate on
+
+        value: the value to insert into a compartment within the target component
+
+        destination_compartment: compartment within component to place a value w/in
+    """
+    component.compartments[destination_compartment] = value
+
+
+def additive(component, value, destination_compartment):
+    """
+    The additive/addition bundle rule routine.
+
+    Args:
+        component: target component node that this bundle rule will operate on
+
+        value: the value to add to current state of compartment w/in target component
+
+        destination_compartment: compartment within component to add a value to
+    """
+    component.compartments[destination_compartment] += value
+
+
+def append(component, value, destination_compartment):
+    """
+    The append/aggregation bundle rule routine. This is primarily useful if
+    the compartment is a list of a values/objects (an appendable list construct).
+
+    Args:
+        component: target component node that this bundle rule will operate on
+
+        value: the value to append to current state of compartment w/in target component
+
+        destination_compartment: compartment within component to append to
+    """
+    component.compartments[destination_compartment].append(value)

ngcsimlib/commands/__init__.py

@@ -0,0 +1,11 @@
+from .command import Command
+from .advanceState import AdvanceState
+from .clamp import Clamp
+from .evolve import Evolve
+from .reset import Reset
+from .track import Track
+from .save import Save
+from .compound import Compound
+from .snapshot import Snapshot
+from .multiclamp import Multiclamp
+

ngcsimlib/commands/advanceState.py

@@ -0,0 +1,25 @@
+from ngcsimlib.commands import Command
+
+
+class AdvanceState(Command):
+    """
+    As the general form, all models built in ngclearn are state machines and this
+    command is designed to advance the state of all of the components passed into
+    the command. Prior to advancing the state of each component, this will call the
+    `gather` method of that component.
+    """
+    def __init__(self, components=None, command_name=None, **kwargs):
+        """
+        Required calls on Components: ['advance_state', 'gather', 'name']
+
+        Args:
+            components: the list of components to advance the state of
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['advance_state', 'gather'])
+
+    def __call__(self, **kwargs):
+        for component in self.components:
+            self.components[component].gather()
+            self.components[component].advance_state(**kwargs)

ngcsimlib/commands/clamp.py

@@ -0,0 +1,58 @@
+from ngcsimlib.commands.command import Command
+from ngcsimlib.utils import extract_args
+
+
+class Clamp(Command):
+    """
+    All components in ngclearn have compartments where they store information
+    pertaining to their internal state that can be read into or out of by
+    commands. The Clamp command is the primary way to manually set the value of
+    a compartment on a set of components. The Clamp command requires a
+    compartment that a value can be passed into and be clamped to,
+    as well as a `clamp_name` used to locate the value when called.
+    """
+
+    def __init__(self, components=None, compartment=None, clamp_name=None,
+                 command_name=None, **kwargs):
+        """
+        Required calls on Components: ['clamp', 'name']
+
+        Args:
+            components: a list of components to call clamp on
+
+            compartment: the compartment being clamped to
+
+            clamp_name: a keyword to bind the input for this command do
+
+            command_name: the name of the command on the controller
+
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['clamp'])
+        if compartment is None:
+            raise RuntimeError(
+                self.name + " requires a \'compartment\' to clamp to for construction")
+        if clamp_name is None:
+            raise RuntimeError(
+                self.name + " requires a \'clamp_name\' to bind to for construction")
+
+        self.clamp_name = clamp_name
+        self.compartment = compartment
+
+        for component in self.components:
+            if self.compartment not in self.components[component].compartments.keys():
+                raise RuntimeError(self.name + " is attempting to "
+                                               "initialize clamp to "
+                                               "non-existent compartment.")
+
+    def __call__(self, *args, **kwargs):
+        try:
+            vals = extract_args([self.clamp_name], *args, **kwargs)
+        except RuntimeError:
+            raise RuntimeError(self.name + ", " + str(
+                self.clamp_name) + " is missing from keyword arguments or a positional "
+                                   "arguments can be provided")
+
+        for component in self.components:
+            self.components[component].clamp(self.compartment, vals[self.clamp_name])
+

ngcsimlib/commands/command.py

@@ -0,0 +1,34 @@
+from abc import ABC, abstractmethod
+from ngcsimlib.utils import check_attributes
+
+
+class Command(ABC):
+    """
+    The base class for all commands found in ngcsimlib. At its core, a command is
+    essentially a method to be called by the controller that affects the
+    components in a simulated complex system / model in some way. When a command
+    is made, a preprocessing step is run to verify that all of the needed
+    attributes are present on each component. Note that this step does not
+    ensure types or values, just that they do or do not exist.
+    """
+    def __init__(self, components=None, command_name=None, required_calls=None):
+        """
+        Required calls on Components: ['name']
+
+        Args:
+            components: a list of components to run the command on
+
+            required_calls: a list of required attributes for all components
+
+            command_name: the name of the command on the controller
+        """
+        self.name = str(command_name)
+        self.components = {}
+        required_calls = ['name'] if required_calls is None else required_calls + ['name']
+        for comp in components:
+            if check_attributes(comp, required_calls, fatal=True):
+                self.components[comp.name] = comp
+
+    @abstractmethod
+    def __call__(self, *args, **kwargs):
+        pass

ngcsimlib/commands/compound.py

@@ -0,0 +1,39 @@
+from ngcsimlib.commands import Command
+from ngcsimlib.utils import check_attributes
+import warnings
+
+class Compound(Command):
+    """
+    There is sometimes a need by controllers to be able to call a set of commands
+    in series without writing custom command(s) for each combination. The
+    compound node/command is used to fill this need. A compound command set is
+    very similar to the cycle found inside/within a controller / simulation object.
+    """
+    def __init__(self, components=None, command_name=None, command_list=None,
+                 controller=None, **kwargs):
+        """
+        Constructs a compound command construct.
+        
+        Args:
+            components: a list of components, this will go unused by default
+
+            command_name: the name of the compound command
+
+            command_list: a list of all commands to be called
+
+            controller: the controller that will be calling these commands
+        """
+        super().__init__(components=components, command_name=command_name)
+        if controller is None:
+            raise RuntimeError("The controller is needed to build a compound command (This should be passed in by default)")
+        if command_list is None or len(command_list) == 0:
+            warnings.warn("The command list for command " + self.name + " is None or empty")
+
+        self.command_list = command_list
+        self.controller = controller
+
+        check_attributes(self.controller, self.command_list, fatal=True)
+
+    def __call__(self, *args, **kwargs):
+        for command in self.command_list:
+            self.controller.runCommand(command, *args, **kwargs)

ngcsimlib/commands/evolve.py

@@ -0,0 +1,41 @@
+from ngcsimlib.commands import Command
+from ngcsimlib.utils import extract_args
+
+class Evolve(Command):
+    """
+    In many models, there is a need to have either a backward pass or a separate
+    method to update some particular internal state (value), e.g., a "learning"
+    or evolutionary change that is not related to central compartment states.
+    In general, this can be mapped to a call of `evolve`. Like with
+    `advanceState`, this will call the gather method prior to calling the
+    `evolve` function of every component.
+
+    """
+    def __init__(self, components=None, frozen_flag=None, command_name=None,
+                 **kwargs):
+        """
+        Required calls on Components: ['evolve', 'gather', 'name']
+
+        Args:
+            components: the list of components to evolve
+
+            frozen_flag: the keyword for the flag to freeze this evolve step
+
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['evolve'])
+
+        self.frozen_flag = frozen_flag
+
+    def __call__(self, *args, **kwargs):
+        vals = {}
+        try:
+            vals = extract_args([self.frozen_flag], *args, **kwargs)
+        except RuntimeError:
+            vals[self.frozen_flag] = False
+
+        if not vals[self.frozen_flag]:
+            for component in self.components:
+                self.components[component].gather()
+                self.components[component].evolve(**kwargs)

ngcsimlib/commands/multiclamp.py

@@ -0,0 +1,42 @@
+from ngcsimlib.commands.command import Command
+from ngcsimlib.utils import extract_args, check_attributes
+
+
+class Multiclamp(Command):
+    """
+    There are times when a model will have many clamp calls as there might be a
+    need to clamp many different values to a model at the same time. As a
+    solution to this, ngcsimlib provides the `multiclamp` command. This command is
+    used to set a wide range of values to all compartments with the same name
+    across all provided compartments.
+    """
+
+    def __init__(self, components=None, clamp_name=None, command_name=None,
+                 **kwargs):
+        """
+        Required calls on Components: ['clamp', 'name']
+        Args:
+            components: a list of components to call clamp on
+
+            clamp_name: a keyword to bind the input for this command do
+
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['clamp'])
+        if clamp_name is None:
+            raise RuntimeError(self.name + " requires a \'clamp_name\' to bind to for construction")
+
+        self.clamp_name = clamp_name
+
+    def __call__(self, *args, **kwargs):
+        try:
+            vals = extract_args([self.clamp_name], *args, **kwargs)
+        except RuntimeError:
+            raise RuntimeError(self.name + ", " + str(self.clamp_name) + " is missing from keyword arguments or a "
+                                                                       "positional arguments can be provided")
+
+        for compartment, value in vals[self.clamp_name].items():
+            for component in self.components:
+                if check_attributes(component, compartment, fatal=False):
+                    self.components[component].clamp(compartment, value)

ngcsimlib/commands/reset.py

@@ -0,0 +1,40 @@
+from ngcsimlib.commands import Command
+from ngcsimlib.utils import extract_args
+import warnings
+
+class Reset(Command):
+    """
+    In every model/system, there is a need to reset components back to some
+    intial state value(s). As such, many components that maintain a state have a
+    reset method implemented within them. The reset command will go through
+    the list of components and trigger the reset within each of them.
+    """
+    def __init__(self, components=None, reset_name=None, command_name=None,
+                 **kwargs):
+        """
+        Required calls on Components: ['reset', 'name']
+
+        Args:
+            components: a list of components to reset
+
+            reset_name: the keyword for the flag on if the reset should happen
+
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['reset'])
+        if reset_name is None:
+            raise RuntimeError(self.name + " requires a \'reset_name\' to bind to for construction")
+        self.reset_name = reset_name
+
+    def __call__(self, *args, **kwargs):
+        try:
+            vals = extract_args([self.reset_name], *args, **kwargs)
+        except RuntimeError:
+            warnings.warn(self.name + ", " + str(self.reset_name) + " is missing from keyword arguments and no "
+                                                             "positional arguments were provided", stacklevel=6)
+            return
+
+        if vals[self.reset_name]:
+            for component in self.components:
+                self.components[component].reset()

ngcsimlib/commands/save.py

@@ -0,0 +1,46 @@
+from ngcsimlib.commands import Command
+from ngcsimlib.utils import extract_args
+import warnings
+
+class Save(Command):
+    """
+    When training models, there is often a need to snapshot the model and save
+    it to disk. The base controller in ngcsimlib is able to save all of the
+    commands, components, connections, and steps to a file in order to rebuild
+    the model at a later time. However, there is a good chance that the model
+    will contain components that have parts that need saving beyond the parameters
+    passed in to initialize the component. ngcsimlib solves this by providing a
+    save command; this command will call a custom save method on all components
+    provided to the command. This custom save method will be responsible for all
+    custom values to be saved and determining where to save them inside of a
+    provided directory.
+    """
+    def __init__(self, components=None, directory_flag=None, command_name=None,
+                 **kwargs):
+        """
+        Required calls on Components: ['save', 'name']
+
+        Args:
+            components: a list of components to call the save function on
+
+            directory_flag: keyword for flag for the directory to save to
+
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['save'])
+        if directory_flag is None:
+            raise RuntimeError(self.name + " requires a \'directory_flag\' to bind to for construction")
+        self.directory_flag = directory_flag
+
+    def __call__(self, *args, **kwargs):
+        try:
+            vals = extract_args([self.directory_flag], *args, **kwargs)
+        except RuntimeError:
+            warnings.warn(self.name + ", " + str(self.directory_flag) + " is missing from keyword arguments and no "
+                                                                "positional arguments were provided", stacklevel=6)
+            return
+
+        if vals[self.directory_flag]:
+            for component in self.components:
+                self.components[component].save(vals[self.directory_flag])

ngcsimlib/commands/snapshot.py

@@ -0,0 +1,39 @@
+from ngcsimlib.commands import Command
+
+class Snapshot(Command):
+    """
+    Sometimes when running through a model, there is a need to extract a value
+    from a compartment to the run loop. As such, ngcsimlib provides the snapshot
+    command. This command will extract a given attribute from all components
+    provided to the command. This command returns a single value if only one
+    component is given, otherwise it will return a list where each value
+    corresponds to the position of the component in the components list.
+
+    This command is regularly used for debugging/graph production code that
+    exists outside of the model. It would be incorrect to clamp the output of
+    this command into another component, if that is the intended goal, please
+    see `connect` in the controller.
+    """
+    def __init__(self, components=None, attribute=None, command_name=None,
+                 **kwargs):
+        """
+        Required calls on Components: ['name'], and the passed-in attribute
+
+        Args:
+            components: the component extract the values of
+
+            attribute: a single attribute to return
+
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=[attribute])
+        self.attribute = attribute
+
+
+    def __call__(self, *args, **kwargs):
+        vals = []
+        for component in self.components:
+            vals.append(getattr(self.components[component], self.attribute))
+
+        return vals if len(vals) > 1 else vals[0]

ngcsimlib/commands/track.py

@@ -0,0 +1,50 @@
+from ngcsimlib.commands import Command
+from ngcsimlib.utils import extract_args
+import warnings
+
+class Track(Command):
+    """
+    When running a model or complex system, there is often a need to track a
+    compartment value over time, usually for visualization. To do this, ngcsimlib
+    provides a track utility command. This command stores the values of a
+    compartment from a set of components into a provided object. This provided
+    object is expected to have an `.append` method implemented and each element
+    appended to this object will be the values of the compartment for each
+    provided component, in the same order that they were provided in.
+    """
+    def __init__(self, components=None, compartment=None, tracker=None,
+                 command_name=None, **kwargs):
+        """
+        Required calls on Components: ['name']
+
+        Args:
+            components: a list of components to track values from
+
+            compartment: the compartment to extract information from
+
+            tracker: the keyword for which the tracking object will be passed in by
+
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name)
+        if compartment is None:
+            raise RuntimeError(self.name + " requires a \'compartment\' to clamp to for construction")
+        if tracker is None:
+            raise RuntimeError(self.name + " requires a \'tracker\' to bind to for construction")
+
+        self.tracker = tracker
+        self.compartment = compartment
+
+
+    def __call__(self, *args, **kwargs):
+        try:
+            vals = extract_args([self.tracker], *args, **kwargs)
+        except RuntimeError:
+            warnings.warn(self.name + ", " + str(self.tracker) + " is missing from keyword arguments and no "
+                                                                "positional arguments were provided", stacklevel=6)
+            return
+
+        v = []
+        for component in self.components:
+            v.append(self.components[component].compartments[self.compartment])
+        vals[self.tracker].append(v)