Docs updates

Author: willgebhardt

docs/compartments.md

@@ -1,14 +1,14 @@
 # Compartments
 
-Within ngcsimlib, the global state serves as the backbone of any given model. 
+Within NGC-Sim-Lib, the global state serves as the backbone of any given model. 
 This global state is essentially the culmination of all of the dynamic or changing parts of the model itself. Each 
 value that builds this state is stored within a special "container" that helps track these changes over time -- this 
-is referred to as a "compartment" (`Compartment`).
+is referred to as a `Compartment`.
 
 ## Practical Information
 
 Practically, when working with compartments, there are a few simple things to keep in mind despite the fact that most 
-of ngcsimlib's primary operation is behind-the-scenes bookkeeping. The two main points to note are: 
+of NGC-Sim-Lib's primary operation is behind-the-scenes bookkeeping. The two main points to note are: 
 1. Each compartment holds a value and, thus, setting a compartment with `myCompartment = newValue` will not function as 
    intended since this will overwrite the Python object, i.e., the compartment with `newValue`. Instead, it is 
    important to make use of the `.set()` method to update the value stored inside a compartment so 
@@ -20,7 +20,7 @@ of ngcsimlib's primary operation is behind-the-scenes bookkeeping. The two main
 ## Technical Information
 
 The follow sections are devoted to explication of more technical information regarding how a compartment functions 
-with in the broader scope of ngcsimlib and, furthermore, to explain how to leverage this information.
+with in the broader scope of NGC-Sim-Lib and, furthermore, to explain how to leverage this information.
 
 ### How Data is Stored (Within a Model Context)
 
@@ -38,7 +38,7 @@ components -- this is at the core of NGC-Learn's and NGC-Sim-Lib's "nodes-and-ca
 through the concept of "targeting,", which is, in essence, just the updating of the path stored within a compartment 
 using the path of a different compartment. This means that, if the targeted compartment goes to retrieve the value 
 stored within it, it will actually retrieve the value of a different compartment (as dictated by the target). When a 
-compartment is in this state -- where it is targeting another compartment -- it is set to read, which only means that 
+compartment is in this state -- where it is targeting another compartment -- it is set to read-only, which only means that 
 it cannot modify a different compartment.
 
 

docs/compiling.md

@@ -1,48 +1,98 @@
 # Compiling
 
-The term "compiling" for ngcsimlib refers to automatic step that happens inside of a context that produces a transformed method for all of its components. This step is the most complicated part of the library and, in general, does not need to be touched or interacted with. Nevertheless, this section will cover all of the steps that the ngcsimlib compilation process does at a high level. This section contains advanced technical/developer-level information: there is an expectation that the reader has an understanding of Python abstract syntax trees (ASTs), globals (global variables), and how to dynamically compile Python code to run/execute.
+The term "compiling" for NGC-Sim-Lib refers to automatic step that happens
+inside of a context that produces a transformed method for all of its
+components. This step is the most complicated part of the library and, in
+general, does not need to be touched or interacted with. Nevertheless, this
+section will cover most of the steps that the NGC-Sim-Lib compilation process
+does at a high level. This section contains advanced technical/developer-level
+information: there is an expectation that the reader has an understanding of
+Python abstract syntax trees (ASTs), Python namespaces, and how to
+dynamically compile Python code and execute it.
 
 ## The Decorator
 
-In ngcsimlib, there is a decorator marked as `@compilable` which is used to add a flag to methods that the user wants to compile. On its own,this will not do anything; however, this decorator lets the parser distinguish between methods that should be compiled and methods that should be ignored (by the overall back-end compilation process).
+In NGC-Sim-Lib, there is a decorator marked as `@compilable` which is used to
+add a flag to methods that the user wants to compile. On its own, this will not
+do anything; however, this decorator lets the parser distinguish between methods
+that should be compiled and methods that should be ignored.
 
 ## The Step-by-Step NGC-Sim-Lib Parsing Process
 
 The process starts by telling the parser to compile a specific object.
 
 ### Step 1: Compile Children
 
-The first step to compile any object is to make sure that all of the "compilable" objects of the top level object are essentially compiled. As a result, ngcsimlib will loop through all of the whole objects and will compile each part that it finds that is flagged as compilable (via the decorators mentioned above) and is, furthermore, an instance of a class.
+The first step to compile any object is to make sure that all of the 
+"compilable" objects of the top level object are compiled. As a
+result, NGC-Sim-Lib will loop through all of the whole object and will compile
+each part that it finds that is flagged as compilable (via the decorators
+mentioned above) and is, furthermore, an instance of a class.
 
 ### Step 2: Extract Methods to Compile
 
-While the parser is looping through all of the parts of the top-level object, it is also extracting the methods on/embedded to the object that are flagged as compilable (with the decorator above). ngcsimlib stores them for later; however, this lets the parser know to only loop over the object once.
+While the parser is looping through all of the parts of the top-level object, it
+is also extracting the methods on/embedded to the object that are flagged as
+compilable (with the decorator above). NGC-Sim-Lib stores them for later;
+however, this lets the parser only loop over the object once.
 
 ### Step 3: Parse Each Method
 
-As each method is its own entry-point into the compiler, this step will run for each method in the top-level object. 
+As each method is its own entry-point into the transformer, this step will run 
+for each method in the top-level object.
 
 ### Step 3a: Set up a Transformer
 
-This step sets up a ContextTransformer, which further makes use of a NodeTransformer, and will convert methods from class methods (with the use of `self`), as well as other methods that need to be removed / ignored, into their more context-friendly counterparts.
+This step sets up a `ContextTransformer`, which further makes use of a
+`ast.NodeTransformer`, and will convert methods from class methods (with the use
+of `self`), as well as other methods that need to be removed / ignored, into
+their more context-friendly counterparts.
 
 ### Step 3b: Transform the Function
 
-There are quite a few pieces of common Python that need to be transformed. This step happens with the overall goal of replacing all object-focused parts with a more global view. This means that a compartment's `.get` and `.set` calls are replaced with direct setting and getting from the global state, based on the compartment's target. This also means that all temporally constant values -- such as `batch_size` -- are moved into the globals space for that specific file and ultimately replaced with the naming convention of `object_path_constant`. One more key step that is performed is to ensure that there is no branching in the code. Specifically, if there is a branch, i.e., an if-statement, ngcsimlib will evaluate it and only keep the branch it will traverse down. This means that there cannot be any branch logic based on inputs or computed values (this is a common restriction for just-in-time compiling). 
+There are quite a few pieces of common Python that need to be transformed. This
+step happens with the overall goal of replacing all object-focused parts with a
+more global view. This means that a compartment's `.get` and `.set` calls are
+replaced with direct setting and getting from the global state, based on the
+compartment's target. This also means that all temporally constant values --
+such as `batch_size` -- are moved into the globals space for that specific file
+and ultimately replaced with the naming convention of `object_path_constant`.
+One more key step that is performed is to ensure that there is no branching in
+the code. Specifically, if there is a branch, i.e., an if-statement, NGC-Sim-Lib
+will evaluate it and only keep the branch it will traverse down. This means that
+there cannot be any branch logic based on inputs or computed values (this is a
+common restriction for just-in-time compiling).
 
 ### Step 3c: Parse Sub-Methods
 
-Since it is possible to have other class methods that are not marked as entry-points for compilation but still need to be compiled, as step 3b happens, ngcsimlib tracks all of the sub-methods required. Notably, this step goes through and repeats steps 3a and 3b for each of the (sub-)methods with a naming convention similar to the temporally constant values for each method.
+Since it is possible to have other class methods that are not marked as
+entry-points for compilation but still need to be compiled, as step 3b happens,
+NGC-Sim-Lib tracks all of the sub-methods required. Notably, this step goes
+through and repeats steps 3a and 3b for each of the (sub-)methods with a naming
+convention similar to the temporally constant values for each method.
 
 ### Step 3d: Compile the Abstract Syntax Tree (AST)
 
-Once we have all of the namespace and globals needed to execute the properly-transformed method, the method is compiled with Python and finally executed.
+Once we have all of the namespace and globals needed to execute the
+properly-transformed method, the method is compiled with Python and finally
+executed.
 
 ### Step 3e: Binding
 
-The final step per method is to bind each to their original method; this replaces each method with an object which, when called, will act like the normal, uncompiled version but has the addition of the `.compiled` attribute. This attribute contains all of the compiled information to be used later (for model / system simulation). This crucially allows for the end user to call `myComponent.myMethod.compiled()` and have it run. The exact type for a `compiled` value can be found in `ngcsimlib._src.parser.utils:CompiledMethod`.
+The final step per method is to bind each to their original method; this
+replaces each method with an object which, when called, will act like the
+normal, uncompiled version but has the addition of the `.compiled` attribute.
+This attribute contains all of the compiled information to be used later (for
+model / system simulation). This crucially allows for the end user to
+call `myComponent.myMethod.compiled()` and have it run. The exact type for
+a `compiled` value can be found
+in `ngcsimlib._src.parser.utils:CompiledMethod`.
 
 ### Step 4: Finishing Up / Final Processing
 
-Some objects, such as the processes, entail additional steps to modify themselves or their compiled methods in order to align themselves with needed functionality. However, this operation/functionality is found within each class's expanded `compile` method and should be referred to by looking at those methods specifically.   
+Some objects, such as the processes, entail additional steps to modify
+themselves or their compiled methods in order to align themselves with needed
+functionality. However, this operation/functionality is found within each
+class's expanded `compile` method and should be referred to by looking at those
+methods specifically.   
 

docs/components.md

@@ -9,13 +9,13 @@ when constructing a complete model of a dynmical system.
 ## Temporally Constant versus Dynamic Compartments
 
 One important distinction that needs to be highlighted within a component is the 
-difference between a temporally constant (or static) value and a dynamic (time-varying) compartment.
+difference between a temporally constant value and a dynamic (time-varying) compartment.
 Compartments themselves house values that change over time and, generally, they will have the 
 type `ngcsimlib.Compartment`; note that compartments are to be used to track the internal values 
 of a component. These internal values can be ones such inputs, decaying values, counters, etc. 
 The second kind of values found within a component are known as temporally constant values; these 
-are values (e.g., hyper-parameters, structural parameters, etc.) that will remain fixed / static 
-with constructed model dynamical system. These types of values tend to include common configuration 
+are values (e.g., hyper-parameters, structural parameters, etc.) that will remain fixed 
+within constructed model dynamical system. These types of values tend to include common configuration 
 and meta-parameter settings, such as matrix shapes and coefficients.
 
 ## Defining Compilable Methods
@@ -28,5 +28,5 @@ value, one must write out such a call as: `self.myCompartment.get()`. The only r
 that any method that is decorated <b>cannot</b> have a return value; values should be stored 
 inside their respective compartments (by making an appeal to their respective set routine, i.e., 
 `self.myCompartment.set(value)`). In an external (compilation) step, outside of the developer's 
-definition of a component, an ngcsimlib transformer will change/convert all of these (decorated) 
-methods into ones that function with the rest of the ngcsimlib back-end.
+definition of a component, an NGC-Sim-Lib transformer will change/convert all of these (decorated) 
+methods into ones that function with the rest of the NGC-Sim-Lib back-end.

docs/context.md

@@ -1,12 +1,12 @@
 # Contexts
 
-Contexts, in ngcsimlib, are the top-level containers that hold everything used to
+Contexts, in NGC-Sim-Lib, are the top-level containers that hold everything used to
 define a model / dynamical system. On their own, contexts have no runtime logic; 
 they rely on their internal processes and components to build a complete, working model.
 
 ## Defining a Context
 
-To define a context (`ngcsimlib.Context`), ngcsimlib leverages the `with` block; this 
+To define a context (`ngcsimlib.Context`), NGC-Sim-Lib leverages the `with` block; this 
 means that to create a new context, simply start with the statement 
 `with Context("myContext") as ctx:` and a new context will be created. 
 (<i>Important Note</i>: names are unique; if a context is created with the same name, 
@@ -46,10 +46,8 @@ steps while inside the `with`-block of the process.
 
 ## Exiting the `with` block
 
-When the context exits the `with`-block, it will re-compile the entire model. This
-means that compilation of all parts of the model that needed to be compiled before 
-usage (such as the compiled methods of a process) needs to happen after the 
-`with`-block is exited. Behind the scenes, this is calling `recompile` on the context 
+When the context exits the `with`-block, it will re-compile the entire model. 
+Behind the scenes, this is calling `recompile` on the context 
 itself; it is possible to manually trigger the recompile step, but doing so can 
 break certain connections (between components/compartments), so use this 
 functionality sparingly.

docs/global_state.md

@@ -1,6 +1,6 @@
 # The Global State
 
-Since ngcsimlib is a simulation library focused on temporal models and dynamical 
+Since NGC-Sim-Lib is a simulation library focused on temporal models and dynamical 
 systems, or models that change over time there, it is foundational that all models 
 (and their respective elements) have some concept of a "state". These states
 might be comprised of a single value that changes/evolves or of a complex set of values
@@ -22,7 +22,7 @@ anything that is needed for your actual model.
 
 ### Adding New Fields to the Global State
 
-If you are new to using ngcsimlib and looking for a way to add values to the
+If you are new to using NGC-Sim-Lib and looking for a way to add values to the
 global state directly and explicitly, stop for a moment and reconsider. Unless 
 you know exactly what you are doing (i.e., doing core development), it is strongly 
 advised to not manually add values to the global state; instead, work through the 

docs/processes.md

@@ -1,6 +1,6 @@
 # Processes
 
-Processes in ngcsimlib offer a central way of defining a specific transition to be 
+Processes in NGC-Sim-Lib offer a central way of defining a specific transition to be 
 taken within a given model (this effectively sets up the behavior of the state-machine 
 that defines the desired dynamical system one wants to simulate). In effect, processes 
 take in as many compilable methods as possible across any number of
@@ -27,14 +27,14 @@ myProcess >> myCompA.forward >> myCompB.forward >> myCompA.evolve >> myCompB.evo
 ```
 
 In both cases, this process will chain the four methods together into a single
-step, only updating the final state that all steps are to complete.
+step, only updating the final state after all steps are complete.
 
 ## Types of Processes
 
 There are two types of processes: the above example would be with what is
 referred to as a `MethodProcess` -- these are used to chain together any
 compilable methods from any number of different components. The other second 
-type of process, called a `JointProcess` in ngcsimlib, is used to chain 
+type of process, called a `JointProcess` in NGC-Sim-Lib, is used to chain 
 together entire processes. 
 JointProcesses are especially useful if there are multiple method processes that
 need to be called but different orders of the processes are needed at different
@@ -85,6 +85,6 @@ iterations of the process. Note that the arguments are slightly different: first
 it now utilizes a `length` argument to indicate the number of rows being produced and, 
 second, it features a `seed_generator` that is used to generate the seed of each row 
 (for instance, to have only even seed values: `seed_generator = lambda x: 2 * x`); if 
-the generator is `None` `seed_generator = lamda x: x` is used. 
+the generator is `None`, then `seed_generator = lamda x: x` is used. 
 After this, the same keyword arguments to define the needed parameters are used as in `pack_keywords`.