ngcsimlib 0.2b0__py3-none-any.whl

ngcsimlib/controller.py

@@ -0,0 +1,378 @@
+from ngcsimlib.utils import check_attributes, load_from_path, make_unique_path, check_serializable
+import json, os, warnings, inspect
+
+
+class Controller:
+    """
+    The ngc controller is the foundation of all ngclearn models and the central
+    operational construct for simulating complex systems. The controller is the
+    object that organizes all of the components, commands, and connections
+    that characterize a complex system and/or model to be simulated over time
+    (and was referred to as the "nodes-and-cables" system in earlier versions of
+    ngc-learn).
+    """
+    def __init__(self):
+        self.steps = []
+        self.commands = {}
+        self.components = {} ## components/nodes that characterize system/simulation object
+        self.connections = []  ## cables that characterize system/simulation object
+
+        self._json_objects = {
+            "commands": [],
+            "steps": [],
+            "components": [],
+            "connections": []
+        }
+
+    def __getitem__(self, item):
+        return self.__getattribute__(item)
+
+    def runCycle(self, **kwargs):
+        """
+        Runs all of the commands that have been added to a "compute" cycle in
+        the order that they were added. All of the keyword arguments that are
+        needed to run the commands within the cycle are passed in here and will
+        ultimately be forwarded to each command.
+
+        Args:
+            kwargs: all keyword arguments that are needed to run every command
+                within the cycle
+        """
+        for step in self.steps:
+            self[step](**kwargs)
+
+    def verify_connections(self, skip_components=None):
+        """
+        Loops through all components within the controller and calls the
+        `verify_connections` method on/for each.
+
+        Args:
+            skip_components: a list of component names to skip over while
+                verifying connections (Default: None)
+        """
+        for component in self.components.keys():
+            if skip_components is not None and component.name in skip_components:
+                continue
+            else:
+                self.components[component].verify_connections()
+
+    def connect(self, source_component_name, source_compartment_name, destination_component_name,
+                target_compartment_name, bundle=None):
+        """
+        Creates a cable from one component to another.
+
+        Args:
+            source_component_name: the name of the component providing the value
+
+            source_compartment_name: the name of the compartment containing the
+                source value
+
+            destination_component_name: the name of the component receiving
+                the value
+
+            target_compartment_name: the name of the compartment to store the
+                source value in
+
+            bundle: the number of the bundle rule to be used when using this
+                cable (Default: None)
+        """
+        self.components[destination_component_name].create_incoming_connection(
+            self.components[source_component_name].create_outgoing_connection(source_compartment_name), target_compartment_name,
+            bundle)
+        self.connections.append((source_component_name, source_compartment_name, destination_component_name, target_compartment_name, bundle))
+        self._json_objects['connections'].append({
+            "source_component_name": source_component_name,
+            "source_compartment_name": source_compartment_name,
+            "target_component_name": destination_component_name,
+            "target_compartment_name": target_compartment_name,
+            "bundle": bundle})
+
+    def make_connections(self, path_to_cables_file):
+        """
+        Loads a collection of cables from a json file. Follow `cables.schema`
+        for the specific format of the required json file.
+
+        Args:
+            path_to_cables_file: the path to the file, including the name and
+                extension
+        """
+        with open(path_to_cables_file, 'r') as file:
+            cables = json.load(file)
+            for cable in cables:
+                self.connect(**cable)
+
+    def make_components(self, path_to_components_file, custom_file_dir=None):
+        """
+        Loads a collection of components from a json file. Follow
+        `components.schema` for the specific format of the json file.
+
+        Args:
+            path_to_components_file: the path to the file, including the name
+                and extension
+
+            custom_file_dir: the path to the custom directory for custom load methods,
+                this directory is named `custom` if the save_to_json method is
+                used. (Default: None)
+        """
+        with open(path_to_components_file, 'r') as file:
+            components = json.load(file)
+            for component in components:
+                self.add_component(**component, directory=custom_file_dir)
+
+    def make_steps(self, path_to_steps_file):
+        """
+        Loads a collection of steps from a json file. Follow `steps.schema` for
+        the specific format of this json file.
+
+        Args:
+            path_to_steps_file: the path of the file, including the name and extension
+        """
+        with open(path_to_steps_file, 'r') as file:
+            steps = json.load(file)
+            for step in steps:
+                self.add_step(**step)
+
+    def make_commands(self, path_to_commands_file):
+        """
+        Loads a collection of commands from a json file. Follow `commands.schema`
+        for the specific format of this json file.
+
+        Args:
+            path_to_commands_file: the path of the file, including the name
+                and extension
+        """
+        with open(path_to_commands_file, 'r') as file:
+            commands = json.load(file)
+            for command in commands:
+                self.add_command(**command)
+
+    def add_step(self, command_name):
+        """
+        Adds a command to the built-in cycle. When the cycle is run/executed,
+        the commands will be called in the order that they are added in (when
+        setting up the controller simulation object).
+
+        Args:
+            command_name: the name of the command to be added
+        """
+        if command_name not in self.commands.keys():
+            raise RuntimeError(str(command_name) + " is not a registered command")
+        self.steps.append(command_name)
+        self._json_objects['steps'].append({"command_name": command_name})
+
+    def add_component(self, component_type, match_case=False, absolute_path=False, **kwargs):
+        """
+        Acts as a component factory for the controller.
+
+        Args:
+            component_type: A string that is linked to the component class to be
+                created. If the class was loaded with the modules.json file this
+                can be the keywords defined in that file. Otherwise, it will have
+                to be dynamically loaded using the functions found in ngcsimlib.utils.
+
+            match_case: A boolean that represents if the exact case should be
+                matched when dynamically loading the component class (Default: False)
+
+            absolute_path: A boolean that represents if the component class
+                should be treated as an absolute path when dynamically loading
+                the component class (Default: False)
+
+            kwargs: All of the keyword arguments that are needed to initialize
+                the loaded component class. The function will try to crash nicely
+                if keyword arguments are missing. This list of arguments will
+                also be stored to allow for the component to be rebuilt, but if
+                a given value is not serializable it will drop that from the
+                keyword arguments.
+
+        Returns:
+            the created component (Component is also automatically added to the controller)
+        """
+        Component_class = load_from_path(path=component_type, match_case=match_case, absolute_path=absolute_path)
+
+        if inspect.isclass(Component_class):
+            call = Component_class.__init__
+        elif inspect.isfunction(Component_class):
+            call = Component_class
+        else:
+            raise RuntimeError("Given component type " + str(component_type)
+                               + " is not callable")
+
+
+
+        count = call.__code__.co_argcount - 1
+        named_args = call.__code__.co_varnames[1:count]
+        try:
+            component = Component_class(**kwargs)
+        except TypeError as E:
+            print(E)
+            raise RuntimeError(str(E) + "\nProvided keyword arguments:\t" + str(list(kwargs.keys())) +
+                               "\nRequired keyword arguments:\t" + str(list(named_args)))
+
+        check_attributes(component, ["name", "verify_connections"], fatal=True)
+        self.components[component.name] = component
+
+        obj = {"component_type": component_type, "match_case": match_case, "absolute_path": absolute_path} | kwargs
+        bad_keys = check_serializable(obj)
+        for key in bad_keys:
+            del obj[key]
+            print("Failed to serialize \"" + str(key) + "\" in " + component.name)
+
+        self._json_objects['components'].append(obj)
+
+        return component
+
+    def add_command(self, command_type, command_name, match_case=False, absolute_path=False, component_names=None,
+                    **kwargs):
+        """
+        Acts as a factory to create/synthesize commands.
+        In addition to adding command objects to the controllers internal
+        command list, commands are also set to their attributes on the controller.
+        For example, if a command named `step` is added myController.runCommand("step", ...)
+        is equivalent to myController.step(...).
+
+        Args:
+            command_type: A string that is linked to the command class to be
+                created. If the class was loaded with the modules.json file this
+                can be the keywords defined in that file. Otherwise, it will
+                have to be dynamically loaded using the functions found
+                in ngcsimlib.utils.
+
+            command_name: A string that is the name of the command, this is the
+                keyword that will be called elsewhere to execute this command.
+
+            match_case: A boolean that represents if the exact case should be
+                matched when dynamically loading the command class (Default: False)
+
+            absolute_path: A boolean that represents if the command class should
+                be treated as an absolute path when dynamically loading the
+                command class (Default: False)
+
+            component_names: A list of component names to be passed to the
+                command's constructor. Internally it will convert the strings to
+                the actual component objects so they must exist in the controller
+                prior to this function being called.
+
+            kwargs: All the keyword arguments that are needed to initialize the
+                loaded command class. The function will try to crash nicely if
+                keyword arguments are missing. This list of arguments will also
+                be stored to allow for the component to be rebuilt, but if a
+                given value is not serializable it will drop that from the
+                keyword arguments.
+
+        Returns:
+            the created command (Command is also automatically added to the controller)
+        """
+        Command_class = load_from_path(path=command_type, match_case=match_case, absolute_path=absolute_path)
+        if not callable(Command_class):
+            raise RuntimeError("The object named \"" + Command_class.__name__ + "\" is not callable. Please make sure "
+                                                                                "the object is callable and returns a "
+                                                                                "callable object")
+        if component_names is not None:
+            componentObjs = [self.components[name] for name in component_names]
+        else:
+            componentObjs = []
+
+        if inspect.isclass(Command_class):
+            call = Command_class.__init__
+        elif inspect.isfunction(Command_class):
+            call = Command_class
+        else:
+            raise RuntimeError("Given command type " + str(command_type)
+                               + " is not callable")
+
+        count = call.__code__.co_argcount - 1
+        named_args = call.__code__.co_varnames[1:count]
+        try:
+            command = Command_class(components=componentObjs, controller=self, command_name=command_name, **kwargs)
+        except TypeError as E:
+            print(E)
+            raise RuntimeError(str(E) + "\nProvided keyword arguments:\t" + str(list(kwargs.keys())) +
+                               "\nRequired keyword arguments:\t" + str(list(named_args)))
+
+        self.commands[command_name] = command
+        self.__setattr__(command_name, command)
+
+        obj = {"command_type": command_type, "command_name": command_name, "match_case": match_case,
+               "absolute_path": absolute_path, "component_names": component_names} | kwargs
+        bad_keys = check_serializable(obj)
+        for key in bad_keys:
+            del obj[key]
+            print("Failed to serialize \"" + str(key) + "\" in " + command_name)
+
+        self._json_objects['commands'].append(obj)
+        return command
+
+    def runCommand(self, command_name, *args, **kwargs):
+        """
+        Runs the given command.
+
+        Args:
+            command_name: the name of the command to run
+
+            args: positional arguments to be passed into the command
+
+            kwargs: keyword arguments to be passed into the command
+        """
+        command = self.commands.get(command_name, None)
+        if command is None:
+            raise RuntimeError("Can not find command: " + str(command_name))
+        command(*args, **kwargs)
+
+    def save_to_json(self, directory, model_name=None, custom_save=True):
+        """
+        Dumps all the required json files to rebuild the current controller to a specified directory. If there is a
+        `save` command present on the controller and custom_save is True, it will run that command as well.
+
+        Args:
+            directory: The top level directory to save the model to
+
+            model_name: The name of the model, if None or if there is already a
+                model with that name a uid will be used or appended to the name
+                respectively. (Default: None)
+
+            custom_save: A boolean that if true will attempt to call the `save`
+                command if present on the controller (Default: True)
+
+        Returns:
+            a tuple where the first value is the path to the model, and the
+                second is the path to the custom save folder if custom_save is
+                true and None if false
+        """
+        path = make_unique_path(directory, model_name)
+
+        with open(path + "/commands.json", 'w') as fp:
+            json.dump(self._json_objects['commands'], fp, indent=4)
+
+        with open(path + "/steps.json", 'w') as fp:
+            json.dump(self._json_objects['steps'], fp, indent=4)
+
+        with open(path + "/components.json", 'w') as fp:
+            json.dump(self._json_objects['components'], fp, indent=4)
+
+        with open(path + "/connections.json", 'w') as fp:
+            json.dump(self._json_objects['connections'], fp, indent=4)
+
+        if custom_save:
+            os.mkdir(path + "/custom")
+            if check_attributes(self, ['save']):
+                self.save(path + "/custom")
+            else:
+                warnings.warn("Controller doesn't have a save command registered. No custom saving happened")
+
+        return (path, path + "/custom") if custom_save else (path, None)
+
+    def load_from_dir(self, directory, custom_folder="/custom"):
+        """
+        Builds a controller from a directory. Designed to be used with
+        `save_to_json`.
+
+        Args:
+            directory: the path to the model
+
+            custom_folder: The name of the custom data folder for building
+                components. (Default: `/custom`)
+        """
+        self.make_components(directory + "/components.json", directory + custom_folder)
+        self.make_connections(directory + "/connections.json")
+        self.make_commands(directory + "/commands.json")
+        self.make_steps(directory + "/steps.json")

ngcsimlib/utils.py

@@ -0,0 +1,237 @@
+"""
+The utilities file for ngcsimlib supports the foundation of how ngclearn does its
+dynamic loading of attributes and modules. When the file is imported, it will
+automatically search for a file (default `json_files/modules.json`, or pass a
+default --modules="json_files/modules.json") to load all the modules for dynamic
+loading. Without this file, when the controller goes on to try to load a component
+or command class, it will be unable to do so/find them. Please see the `modules.schema`
+file in the `json_schemes` folder for more details on how to create the
+modules.json file.
+"""
+import sys, uuid, os, json
+from importlib import import_module
+
+## Globally tracking all the modules, and attributes have been dynamically loaded
+_Loaded_Attributes = {}
+_Loaded_Modules = {}
+
+
+def check_attributes(obj, required, fatal=False):
+    """
+    This function will verify that a provided object has the requested attributes.
+
+    Args:
+        obj: Object that should have the attributes
+
+        required: A list of required attributes by string name
+
+        fatal: If true an Attribute error will be thrown (default False)
+
+    Returns:
+        Boolean only returns if not fatal, if the object has the required attributes
+    """
+    if required is None:
+        return True
+    for atr in required:
+        if not hasattr(obj, atr):
+            if not fatal:
+                return False
+            if hasattr(obj, "name"):
+                raise AttributeError(str(obj.name) + " is missing the required attribute of " + atr)
+            else:
+                raise AttributeError("Checked object is missing the required attribute of " + atr)
+    return True
+
+
+def load_module(module_path, match_case=False, absolute_path=False):
+    """
+    Trys to load a module from the provided path.
+
+    Args:
+        module_path: Module path, supports compound modules such as `ngcsimlib.commands`
+
+        match_case: If true the module must case match exactly (default false)
+
+        absolute_path: If true tries to import exactly what is passed to module
+            path (default false)
+
+    Returns:
+        the module that has been loaded
+    """
+    #Return if we have already loaded this module
+    if module_path in _Loaded_Modules.keys():
+        return _Loaded_Modules[module_path]
+    #Unkown module
+    module_name = None
+    if absolute_path:
+        module_name = module_path
+    else:
+        #Extract the final module from the module_path
+        final_mod = module_path.split('.')[-1]
+        final_mod = final_mod if match_case else final_mod.lower()
+
+        #Try to match the final module to any currently loaded module
+        for module in sys.modules:
+            last_mod = module.split('.')[-1]
+            last_mod = last_mod if match_case else last_mod.lower()
+            if final_mod == last_mod:
+                print("Loading module from " + module)
+                module_name = module
+                break
+
+        #Will only be None if no imported modules match the import name
+        if module_name is None:
+            raise RuntimeError("Failed to find dynamic import for \"" + module_path + "\"")
+
+    mod = import_module(module_name)
+    _Loaded_Modules[module_path] = mod
+    return mod
+
+def load_from_path(path, match_case=False, absolute_path=False):
+    """
+    Loads an attribute/module from a specified path. If not using the absolute path the module name and attribute
+    names will be assumed to be the same.
+
+    Args:
+        path: path to attribute/module to load, will try to find the attribute/module if not already loaded
+
+        match_case: If true the module must case match exactly (default false)
+
+        absolute_path: If true tries to import exactly what is passed to module path (default false)
+
+    Returns:
+        The attribute at the path
+    """
+    if absolute_path is True:
+        module_name = '.'.join(path.split('.')[:-1])
+        class_name = path.split('.')[-1]
+        match_case = True
+    else:
+        module_name = path
+        class_name = path
+
+    return load_attribute(module_path=module_name, attribute_name=class_name,
+                          match_case=match_case, absolute_path=absolute_path)
+
+
+def load_attribute(attribute_name, module_path=None, match_case=False, absolute_path=False):
+    """
+    Loads a specific attribute from a specified module
+
+    Args:
+        attribute_name: name of the attribute to load
+
+        module_path: module to load the attribute from, will use the attribute
+            name if None (default None)
+
+        match_case: If true the module must case match exactly (default false)
+
+        absolute_path: If true tries to import exactly what is passed to module
+            path (default false)
+
+    Returns:
+        the loaded attribute
+    """
+    if attribute_name in _Loaded_Attributes.keys():
+        return _Loaded_Attributes[attribute_name]
+
+    if attribute_name is None:
+        raise RuntimeError()
+
+    mod = load_module(attribute_name if module_path is None else module_path, match_case=match_case, absolute_path=absolute_path)
+
+    attribute_name = attribute_name if match_case else attribute_name[0].upper() + attribute_name[1:]
+
+    try:
+        attr = getattr(mod, attribute_name)
+    except AttributeError:
+        raise RuntimeError("Could not find an attribute with name \"" + attribute_name + "\" in module " + mod.__name__) \
+            from None
+
+    _Loaded_Attributes[attribute_name] = attr
+    return attr
+
+def make_unique_path(directory, root_name=None):
+    """
+    This block of code will make a uniquely named directory inside the specified output folder.
+    If the root name already exists it will append a UID to the root name to not overwrite data
+
+    Args:
+        directory: The root directory to save models to
+
+        root_name: (Default None) The root name for the model to be saved to,
+            if none it will just use the UID
+
+    Returns:
+        path to created directory
+    """
+    uid = uuid.uuid4()
+    if root_name is None:
+        root_name = str(uid)
+        print("generated path will be named \"" + str(root_name) + "\"")
+
+    elif os.path.isdir(directory + "/" + root_name):
+        root_name += "_" + str(uid)
+        print("root path already exists, generated path will be named \"" + str(root_name) + "\"")
+
+    path = directory + "/" + str(root_name)
+    os.mkdir(path)
+    return path
+
+
+def check_serializable(dict):
+    """
+    Verifies that all the values of a dictionary are serializable
+
+    Args:
+        dict: dictionary to check
+
+    Returns:
+        list of all the keys that are not serializable
+    """
+    bad_keys = []
+    for key in dict.keys():
+        try:
+            json.dumps(dict[key])
+        except:
+            bad_keys.append(key)
+    return bad_keys
+
+
+def extract_args(keywords=None, *args, **kwargs):
+    """
+    Extracts the given keywords from the provided args and kwargs. This method first finds all the matching keywords
+    then for each missing keyword it takes the next value in args and assigns it. It will throw and error if there are
+    not enough kwargs and args to satisfy all provided keywords
+
+    Args:
+        keywords: a list of keywords to extract
+
+        args: the positional arguments to use as a fallback over keyword arguments
+
+        kwargs: the keyword arguments to first try to extract from
+
+    Returns:
+        a dictionary for where each keyword is a key, and the value is assigned
+            argument. Will throw a RuntimeError if it fails to match and argument
+            to each keyword.
+    """
+    if keywords is None:
+        return None
+
+    a = {key: None for key in keywords}
+    missing = []
+    for key in keywords:
+        if key in kwargs.keys():
+            a[key] = kwargs.get(key, None)
+        else:
+            missing.append(key)
+
+    if len(missing) > len(args):
+        raise RuntimeError("Missing arguments")
+
+    else:
+        for idx, key in enumerate(missing):
+            a[key] = args[idx]
+
+    return a

ngcsimlib-0.2b0.dist-info/AUTHORS

@@ -0,0 +1,10 @@
+# This file contains an official list of authors of this framework.
+
+# Names should be added to this file as:
+# Name or Organization <email address>
+# The email address is not required for organizations.
+
+Core Team
+William Gebhardt <wdg1351@rit.edu>
+Alexander Ororbia <ago@cs.rit.edu>
+

ngcsimlib-0.2b0.dist-info/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, The Neural Adaptive Computing Laboratory
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.