cleaned/revised docs/final nudge to 1.0.0 -- these changes move to release now

Author: Alexander Ororbia

AUTHORS

@@ -8,3 +8,5 @@ Core Team
 William Gebhardt <[email protected]>
 Alexander Ororbia <[email protected]>
 
+Contributors 
+Viet Dung Nguyen <[email protected]>

README.md

@@ -23,7 +23,7 @@ maintained by the
 
 <i>Setup:</i> Ensure that you have installed the following base dependencies in
 your system. Note that this library was developed and tested on
-Ubuntu 22.04.3 LTS. ngc-sim-lib requires: `Python (>=3.8)`.
+Ubuntu 22.04.3/5 LTS. ngc-sim-lib requires: `Python (>=3.10)`.
 
 Once you have ensured that the appropriate Python is installed, you can then
 have the <code>ngcsimlib</code> package installed on your system using either 

ngcsimlib/compartment.py

@@ -37,6 +37,7 @@ def __init__(self, initial_value=None, static=False, is_input=False,
         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
@@ -60,7 +61,7 @@ def __init__(self, initial_value=None, static=False, is_input=False,
     def _setup(self, current_component, key):
         """
         Finishes initializing the compartment, called by the component that
-        builds the compartment
+        builds the compartment 
         (Handled automatically)
         """
         self.__add_connection = current_component.add_connection
@@ -72,6 +73,7 @@ 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
         """
@@ -124,7 +126,6 @@ def is_wired(self):
         """
         Returns: if this compartment not marked as an input, or is marked and
         has an input
-
         """
         if not self.is_input:
             return True

ngcsimlib/compilers/process.py

@@ -40,7 +40,8 @@ class Process(object):
     """
     def __init__(self, name):
         """
-        Creates and empty process using the provided name
+        Creates an empty process using the provided name
+
         Args:
             name: the name of the process (should be unique per context)
         """
@@ -57,15 +58,16 @@ def __init__(self, name):
     @staticmethod
     def make_process(process_spec, custom_process_klass=None):
         """
-        Used the in the creation of a process from a json file. Under normal
-        circumstances this is not normally called by the user.
+        Used in the creation of a process from a json file. Under normal
+        circumstances this is not normally to be called by the user.
 
         Args:
             process_spec: the parsed json object to create a process from
-            custom_process_klass: a custom subclass of a process to build
 
-        Returns: the created process
+            custom_process_klass: a custom subclass of a process to build
 
+        Returns: 
+            the created process
         """
         if custom_process_klass is None:
             custom_process_klass = Process
@@ -81,17 +83,20 @@ def make_process(process_spec, custom_process_klass=None):
     @property
     def pure(self):
         """
-        Returns: The current compile method for the process as a pure method
+        Returns: 
+            the current compile method for the process as a pure method
         """
         return self._method
 
     def __rshift__(self, other):
         """
-        Added wrapper for the transition method
+        Added wrapper for the transition method.
+
         Args:
             other: the transition call for the transition method
 
-        Returns: the process for the use of chaining calls
+        Returns: 
+            the process for the use of chaining calls
         """
         return self.transition(other)
 
@@ -101,10 +106,10 @@ def transition(self, transition_call):
         decorated by the @transition decorator.
 
         Args:
-            transition_call: Transition method to add to the process
-
-        Returns: the process for the use of chaining calls
+            transition_call: transition method to add to the process
 
+        Returns: 
+            the process for the use of chaining calls
         """
         self._calls.append({"path": transition_call.__self__.path, "key": transition_call.resolver_key})
         self._needed_contexts.add(infer_context(transition_call.__self__.path))
@@ -119,19 +124,19 @@ def execute(self, update_state=False, **kwargs):
         """
         Executes the process using the current state of the model to run. This
         method has checks to ensure that the process has transitions added to it
-        as well as that all the keyword arguments required by each of the
-        transition call are in the provided keyword arguments. By default, this
+        as well as if all of the keyword arguments required by each of the
+        transition calls are in the provided keyword arguments. By default, this
         does not update the final state of the model but that can be toggled
         with the flag "update_state".
 
         Args:
-            update_state: Should this method update the final state of the model
-            **kwargs: The required keyword arguments to execute the process
+            update_state: should this method update the final state of the model?
 
-        Returns: the final state of the process regardless of the model is
-        updated to reflect this. Will return null if either of the above checks
-        fail
+            **kwargs: the required keyword arguments to execute the process
 
+        Returns: 
+            The final state of the process regardless of the model is updated to 
+            reflect this. Will return null/None if either of the above checks fail
         """
         if self._method is None:
             warn("Attempting to execute a process with no transition steps")
@@ -147,14 +152,15 @@ def execute(self, update_state=False, **kwargs):
 
     def as_obj(self):
         """
-        Returns: Returns this process as an object to be used with json files
+        Returns: 
+            Returns this process as an object to be used with json files
         """
         return {"name": self.name, "class": self.__class__.__name__, "calls": self._calls}
 
     def get_required_args(self):
         """
-        Returns: The needed arguments for all the transition calls in this
-        process as a set
+        Returns: 
+            The needed arguments for all the transition calls in this process as a set
         """
         return self._needed_args
 
@@ -164,14 +170,15 @@ def get_required_state(self, include_special_compartments=False):
         note that if this is going to be used as an argument to the pure method
         make sure that the "include_special_compartments" flag is set to True so
         that special compartments found in certain components are visible.
+
         Args:
             include_special_compartments: A flag to show the compartments that
-            denoted as special compartments by ngcsimlib (this is any
-            compartment with * in their name, these are can only be created
-            dynamically)
-
-        Returns: A subset of the model state based on the required compartments
+                denoted as special compartments by ngcsimlib (this is any
+                compartment with * in their name, these are can only be created
+                dynamically)
 
+        Returns: 
+            A subset of the model state based on the required compartments
         """
         compound_state = {}
         for context in self._needed_contexts:
@@ -181,38 +188,40 @@ def get_required_state(self, include_special_compartments=False):
     def updated_modified_state(self, state):
         """
         Updates the model with the provided state. It is important to note that
-        only values that are rquired for the execution of this process will be
-        affected by this call. If all compartments need to be updated, view
-        other options found in ngcsimlib.utils.
+        only values that are required for the execution of this process will be
+        affected by this call. If all of the compartments need to be updated, view
+        other options found in `ngcsimlib.utils`.
+        
         Args:
-            state: The state to update the model with
+            state: the state to update the model with
         """
         Set_Compartment_Batch({key: value for key, value in state.items() if key in self.get_required_state(include_special_compartments=True)})
 
 
 def transition(output_compartments, builder=False):
     """
-    The decorator to be paired with the Process call. This method does
+    The decorator to be paired with the `Process` call. This method does
     everything that the now outdated resolver did to ensure backward
-    compatability. This decorator expects to decorate a static method on a
-    class.
+    compatability. This decorator expects the user/developer to decorate a 
+    static method on a class.
 
-    Through normal patterns these decorated method will never be directly called
+    Through normal patterns, these decorated method will never be directly called
     by the end user, but if they are for the purpose of debugging there are a
-    few things to keep in mind. While the process compiler will automatically
+    few things to keep in mind. The process compiler will automatically
     link values in the component to the different values to be passed into the
     method that does not exist if they are directly called. In addition, if the
     method is going to be called at a class level the first value passed into
     the method must be None to not mess up the internal decoration.
-    Args:
-        output_compartments: The string name of the output compartments the
-        outputs of this method will be assigned to in the order they are output.
-        builder: A boolean flag for if this method is a builder method for the
-        compiler. A builder method is a method that returns the static method to
-        use in the transition.
-
-    Returns: the wrapped method
 
+    Args:
+        output_compartments: the string name of the output compartments the
+            outputs of this method will be assigned to in the order they are output.
+            builder: A boolean flag for if this method is a builder method for the
+            compiler. A builder method is a method that returns the static method to
+            use in the transition.
+
+    Returns: 
+        the wrapped method
     """
     def _wrapper(f):
         @wraps(f)
@@ -238,4 +247,5 @@ def inner(self, *args, **kwargs):
         add_transition_meta(class_name, resolver_key,([], [], [], True))
 
         return inner
-    return _wrapper
+    return _wrapper
+

ngcsimlib/compilers/process_compiler/component_compiler.py

@@ -1,11 +1,11 @@
 """
-This file contains the methods used to compile methods for the use of Processes.
+This file contains the methods used to compile methods for the use of Process(es).
 The general methodology behind this compiler is that if all transitions can be
-expressed as f(current_state, **kwargs) -> final_state they can then be composed
+expressed as f(current_state, **kwargs) -> final_state, then they can then be composed
 together as f(g(current_state, **kwargs) **kwargs) -> final_state. While it is
-technically possible to use the compiler outside the process its intended use
-case is through the process and thus if error occur though other uses support
-may be minimal.
+technically possible to use the compiler outside the process, its intended use
+case is through the process and, thus, if errors occur through other uses, note 
+that support may be minimal.
 """
 
 from ngcsimlib.compilers.process_compiler.op_compiler import compile as op_compile
@@ -31,14 +31,15 @@ def _builder(transition_method_to_build):
 def compile(transition_method):
     """
     This method is the main compile method for the process compiler. Unlike the
-    legacy compiler this compiler is designed to be self-contained and output
+    legacy compiler, this compiler is designed to be self-contained and output
     the methods that are composed together to make the process compiler function
+
     Args:
         transition_method: a method usually component.method that has been
-        decorated by the @transition decorator.
+            decorated by the @transition decorator.
 
-    Returns: the pure compiled method of the form
-    f(current_state, **kwargs) -> final_state)
+    Returns: 
+        the pure compiled method of the form f(current_state, **kwargs) -> final_state)
 
     """
     composition = None
@@ -93,3 +94,4 @@ def compiled(current_state, **kwargs):
     composition = compose(composition, compiled)
 
     return composition, needed_args
+

ngcsimlib/compilers/process_compiler/op_compiler.py

@@ -5,13 +5,14 @@ def _make_lambda(s):
 
 def compile(op):
     """
-        compiles root operation down to a single method of
-        f(current_state, **kwargs) -> final_state
+    Compiles root operation down to a single method of 
+    f(current_state, **kwargs) -> final_state
 
     Args:
         op: the operation to compile
 
-    Returns: the compiled operation
+    Returns: 
+        the compiled operation
     """
     arg_methods = []
     for s in op.sources:
@@ -29,4 +30,5 @@ def compiled(current_state, **kwargs):
         else:
             return val
 
-    return compiled
+    return compiled
+

ngcsimlib/compilers/utils.py

@@ -5,7 +5,7 @@ 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
+    be used with compiled commands.
 
     Args:
         command: the command to wrap
@@ -28,3 +28,4 @@ def compose(current_composition, next_method):
 
     return lambda current_state, **kwargs: next_method(
         current_composition(current_state, **kwargs), **kwargs)
+

ngcsimlib/component.py

@@ -55,7 +55,8 @@ def validate(self):
         """
         Validates that each compartment of the component is wired correctly
 
-        Returns: if it is valid
+        Returns: 
+            if this component is valid
         """
         valid = True
         for key, item in self.__dict__.items():
@@ -75,4 +76,4 @@ def validate(self):
                         msg += f"\nCompartment Description:\t{_help}"
                     warn(msg)
                     valid = False
-        return valid
+        return valid

ngcsimlib/configManager.py

@@ -41,6 +41,7 @@ def init_config(path):
     """
     Initializes the global configuration from the provided path
     (called automatically)
+
     Args:
         path: path to config file
     """