Comments and cleanup (#9)

* Added every comment for new simlib routines/functions
* Fixed duplicated wrapped init calls
* Changed compiled methods to use kwargs

End user function still take in regular arguments -- only the internals have changed.
Calling compiled functions now requires kwargs not args

Author: willgebhardt

ngcsimlib/commands/clamp.py

@@ -1,7 +1,7 @@
 from ngcsimlib.commands.command import Command
 from ngcsimlib.utils import extract_args
-from ngcsimlib.componentUtils import find_compartment
-from ngcsimlib.logger import warn, error
+from ngcsimlib.logger import error
+from ngcsimlib.compartment import Compartment
 
 class Clamp(Command):
     """
@@ -39,16 +39,14 @@ def __init__(self, components=None, compartment=None, clamp_name=None,
         self.compartment = compartment
 
         for name, component in self.components.items():
-            _, mapped_name = find_compartment(component.compartments, component.__class__, self.compartment)
+            mapped = hasattr(component, self.compartment)
+            if mapped:
+                if Compartment.is_compartment(getattr(compartment, self.compartment)):
+                    continue
 
-            if mapped_name is None:
-                error(self.name, " is attempting to initialize clamp to non-existent compartment \"",
-                      self.compartment, "\" on ", name, sep=" ")
+            error(self.name, " is attempting to initialize clamp to non-existent compartment \"",
+                  self.compartment, "\" on ", name, sep=" ")
 
-            if mapped_name != self.compartment:
-                warn(self.name, " is attempting to initialize clamp to a property name, not a compartment of ", name,
-                     ". If using a verboseDict and autoMap this will work, otherwise this clamp will have unknown "
-                     "behavior", sep=" ")
 
     def __call__(self, *args, **kwargs):
         try:

ngcsimlib/compartment.py

@@ -4,12 +4,39 @@
 
 
 class Compartment:
+    """
+    Compartments in ngcsimlib are container objects for storing the stateful values of components. Compartments are
+    tracked globaly and are automatically linked to components and methods during compiling to allow for stateful
+    mechanics to be run without the need for the class object. Compartments also provide an entry and exit point for
+    values inside of components allowing for cables to be connected for sending and receiving values.
+    """
+
     @classmethod
     def is_compartment(cls, obj):
+        """
+        A method for verifying if a provided object is a compartment. All compartments have `_is_compartment` set to
+        true by default and this is
+
+        Args:
+            obj: The object to check if it is a compartment
+
+        Returns:
+            boolean if the provided object is a compartment
+        """
         return hasattr(obj, "_is_compartment")
 
     def __init__(self, initial_value=None, static=False):
+        """
+        Builds a compartment to be used inside a component. It is important to note that building compartments
+        outside of components may cause unexpected behavior as components interact with their compartments during
+        construction to finish initializing them.
+        Args:
+            initial_value: The initial value of the compartment. As a general practice it is a good idea to
+                provide a value that is similar to the values that will normally be stored here, such as an array of
+                zeros of the correct length. (default: None)
 
+            static: a flag to lock a compartment to be static (default: False)
+        """
         self._is_compartment = True
         self.__add_connection = None
         self._static = static
@@ -19,27 +46,55 @@ def __init__(self, initial_value=None, static=False):
         self.path = None
 
     def _setup(self, current_component, key):
+        """
+        Finishes initializing the compartment, called by the component that builds the compartment
+        (Handel automatically)
+        """
         self.__add_connection = current_component.add_connection
         self.name = current_component.name + "/" + key
         self.path = get_current_path() + "/" + self.name
         Set_Compartment_Batch({str(self.path): self})
 
     def set(self, value):
+        """
+        Sets the value of the compartment if it not static (Raises a runtime error)
+        Args:
+             value: the new value to be set
+        """
         if not self._static:
             self.value = value
         else:
             raise RuntimeError("Can not assign value to static compartment")
 
     def clamp(self, value):
+        """
+        A wrapper for the set command
+        """
         self.set(value)
 
     def __repr__(self):
+        """
+        Returns:
+             returns the name of the compartment
+        """
         return f"[{self.name}]"
 
     def __str__(self):
+        """
+        Returns:
+             returns the string representation of the value of the compartment
+        """
         return str(self.value)
 
     def __lshift__(self, other) -> None:
+        """
+        Overrides the left shift operation to be used for wiring compartments into one another
+        if other is not an Operation it will create an overwrite operation with other as the argument,
+        otherwise it will use the provided operation
+
+        Args:
+            other: Either another component or an instance of BaseOp
+        """
         if isinstance(other, BaseOp):
             other.set_destination(self)
             self.__add_connection(other)

ngcsimlib/compilers/__init__.py

@@ -1,3 +1,3 @@
-from .command_compiler import compile as compile_command, dynamic_compile, wrap_command
+from .command_compiler import compile_command, dynamic_compile, wrap_command
 from .component_compiler import compile as compile_component
 from .op_compiler import compile as compile_op

ngcsimlib/compilers/command_compiler.py

@@ -1,9 +1,60 @@
+"""
+This is the file that contains the code to compile a given command on a model.
+
+There are a few ways to compile the commands for a model, firstly if there is a command object already initialized
+that has a valid compile key and a list of components the base method of `compile_command(command)` can be used to produce
+the desired output. If no command object has been initialized then the `dynamic_compile(*components, compile_key=None)`
+can be used to produce the desired output without the need to first go through a command object. The output of either
+compile method will be the same.
+
+The output produced by compiling a command will be two objects.
+
+The first object produced by compiling a command is the compiled method itself. This method requires at least one
+positional argument and then any number of additional arguments. The first argument that is provided to the compiled
+method is a python dictionary that contains the state for all compartments this method will need to access,
+as discerning this can be a challenge it is normal to just pass it all compartments present on your model. The
+remaining list of arguments are all the run time arguments that the various compiled methods need to run properly.
+The return value of this compiled method is the final state of all compartments after running through the compiled
+command. Note here that the value on the compartments are not automatically updated and that will need to be done after.
+
+The second object produced by compiling a command is the list of arguments that the compile command is expecting to
+be passed in alongside the initial state of all the compartments. It is a good habit to get into printing this list
+out after compiling as it can help catch typos present in the compiled methods that will not cause the compiling to
+fail but will produce unknown behavior.
+
+There is a wrapper method offered in this file we recommend using to assist with the design patterned required by the
+compiled command. This is done with `wrap_command(command)`. This method will return another method that removes the
+need for creating the initial state of the compartments and setting all the compartment values after running. Arguments
+are still required to be passed in at run time.
+
+"""
 from ngcsimlib.compilers.component_compiler import parse as parse_component, compile as compile_component
 from ngcsimlib.compilers.op_compiler import parse as parse_connection
 from ngcsimlib.utils import Get_Compartment_Batch, Set_Compartment_Batch
-
+from ngcsimlib.logger import critical
 
 def _compile(compile_key, components):
+    """
+    This is the top level compile method for commands. Note this does not actually require you to compile a
+    specific command object as it works purely off the compile key provided to the method.
+    The general process that this takes to compile down everything, is by producing an execution order that knows which
+    methods that are going to be called and where the results of the method are supposed to be stored.
+
+    The execution order is as follows:
+
+    For each component in the provided array of components;
+    | compile it with the provided key
+    | resolve the outputs of the compiled function
+
+    Args:
+        compile_key: The key that is being compiled (mapped to each function that has the @resolver decorator
+                    above it)
+
+        components: The list of components to compile for this function
+
+    Returns:
+        Produces the two objects described at the top of this file
+    """
     assert compile_key is not None
     ## for each component, get compartments, get output compartments
     resolvers = {}
@@ -30,15 +81,20 @@ def _compile(compile_key, components):
             path = str(component.__dict__[comp].path)
             if path not in needed_comps:
                 needed_comps.append(path)
-    arg_order = needed_args + needed_comps
+
     exc_order = []
     for c_name, component in components.items():
-        exc_order.extend(compile_component(component, resolvers[c_name], arg_order))
+        exc_order.extend(compile_component(component, resolvers[c_name]))
+
+    def compiled(compartment_values, **kwargs):
+        for n in needed_args:
+            if n not in kwargs:
+                critical(f"Missing keyword argument \"{n}\" in compiled function."
+                         f"\tExpected keyword arguments {needed_args}")
 
-    def compiled(compartment_values, *cargs):
         for exc, outs, name in exc_order:
-            _comps = [compartment_values[key] for key in needed_comps]
-            vals = exc(*cargs, *_comps)
+            _comps = {key: compartment_values[key] for key in needed_comps}
+            vals = exc(**kwargs, **_comps)
             if len(outs) == 1:
                 compartment_values[outs[0]] = vals
             elif len(outs) > 1:
@@ -49,16 +105,49 @@ def compiled(compartment_values, *cargs):
     return compiled, needed_args
 
 
-def compile(command):
+def compile_command(command):
+    """
+    Compiles a given command object to the spec described at the top of this file
+
+    Args:
+        command: the command object
+
+    Returns:
+        compiled_command, needed_arguments
+
+    """
     return _compile(command.compile_key, command.components)
 
 
 def dynamic_compile(*components, compile_key=None):
+    """
+    Dynamically compiles a command without the need of a command object to produce
+    the spec described at the top of this file.
+
+    Args:
+        *components: a list of components to be compiled
+
+        compile_key: the compile key specifying what to compile
+
+    Returns:
+        compiled_command, needed_arguments
+    """
     assert compile_key is not None
     return _compile(compile_key, {c.name: c for c in components})
 
 
 def wrap_command(command):
+    """
+    Wraps the provided command to provide the state of all compartments as input
+    and saves the returned state to all compartments after running. Designed to
+    be used with compiled commands
+
+    Args:
+        command: the command to wrap
+
+    Returns:
+        the output of the command after it's been executed
+    """
     def _wrapped(*args):
         vals = command(Get_Compartment_Batch(), *args)
         Set_Compartment_Batch(vals)

ngcsimlib/compilers/component_compiler.py

@@ -1,10 +1,38 @@
-from ngcsimlib.compilers.op_compiler import compile as op_compile
+"""
+This is the file that contains the code to compile a component for a command.
+
+There are two primary method provided in this file. The first of them is the parse command. This command is designed
+to provide everything that is needed to compile the component down without actually doing so. This is generally used
+by the command compiler to produce a working list of everything that is needed prior to the actual compiling of all
+components.
 
+The second method that is provided in this file the actual method for compiling the component. This method takes in
+the component, the parsed component, and the global argument order for the compiled method. The result of this method
+is the execution order needed to be run to compute the compiled method over this component. This execution order is
+consistent with the same pattern used by the command compiler.
+
+"""
+from ngcsimlib.compilers.op_compiler import compile as op_compile
 from ngcsimlib.utils import get_resolver
 from ngcsimlib.compartment import Compartment
 
 
 def parse(component, compile_key):
+    """
+    Returns the parsed version of a component for use in compiling
+
+    Args:
+        component: the component to parse
+
+        compile_key: the key to parse with
+
+    Returns: the pure function,
+             the output compartments to resolve to,
+             the arguments needed,
+             the parameters needed,
+             the compartments needed
+
+    """
     (pure_fn, output_compartments), (args, parameters, compartments, parse_varnames) = \
         get_resolver(component.__class__.__name__, compile_key)
 
@@ -28,45 +56,36 @@ def parse(component, compile_key):
     return (pure_fn, output_compartments, args, parameters, compartments)
 
 
-def compile(component, resolver, arg_order):
+def compile(component, resolver):
+    """
+        compiles down the component to a single pure method
+
+    Args:
+        component: the component to compile
+
+        resolver: the parsed output of the component
+
+    Returns:
+        the compiled method
+    """
     exc_order = []
     pure_fn, outs, _args, params, comps = resolver
 
     ### Op resolve
     for connection in component.connections:
-        exc_order.append(op_compile(connection, arg_order))
+        exc_order.append(op_compile(connection))
 
     ### Component resolve
     comp_ids = [str(component.__dict__[comp].path) for _, comp in comps]
     out_ids = [str(component.__dict__[comp].path) for comp in outs]
 
-    funParams = [component.__dict__[narg] for _, narg in (list(params))]
-
-    arg_locs = [loc for loc, _ in _args]
-    param_locs = [loc for loc, _ in params]
-    comp_locs = [loc for loc, _ in comps]
+    funParams = {narg: component.__dict__[narg] for _, narg in (list(params))}
 
-    def compiled(*args):
-        funArgs = [args[arg_order.index(narg)] for _, narg in (list(_args))]
-        funComps = [args[arg_order.index(narg)] for narg in comp_ids]
-
-        _arg_loc = 0
-        _param_loc = 0
-        _comps_loc = 0
-
-        fargs = []
-        for i in range(len(arg_locs) + len(param_locs) + len(comp_locs)):
-            if i in arg_locs:
-                fargs.append(funArgs[_arg_loc])
-                _arg_loc += 1
-            elif i in param_locs:
-                fargs.append(funParams[_param_loc])
-                _param_loc += 1
-            else:
-                fargs.append(funComps[_comps_loc])
-                _comps_loc += 1
+    def compiled(**kwargs):
+        funArgs = {narg: kwargs.get(narg) for _, narg in (list(_args))}
+        funComps = {narg.split('/')[-1]: kwargs.get(narg) for narg in comp_ids}
 
-        return pure_fn(*fargs)
+        return pure_fn(**funParams, **funArgs, **funComps)
 
     exc_order.append((compiled, out_ids, component.name))
     return exc_order