revised/cleaned-up docs

Author: Alexander Ororbia

docs/compartments.md

@@ -1,49 +1,44 @@
 # Compartments
 
-Inside ngcsimlib there is the global state as the backbone of any given model.
-This global state is the culmination of all the dynamic or changing parts of the
-model. Each value that builds this state is stored in a special container that
-helps track these changes known as a Compartment.
+Within ngcsimlib, 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`).
 
 ## Practical Information
 
-Practically when working with compartments there are a few simple things to keep
-in mind and the rest is all behind the scenes bookkeeping. The first piece to
-keep in mind is that each compartment holds a value and thus setting a
-compartment with `myCompartment = newValue` will not function as intended as
-this will overwrite the python object that is the compartment with `newValue`.
-Instead, make use of the `.set()` method to update the value stored inside a
-compartment so `myCompartment = newValue` becomes `myCompartment.set(newValue)`.
-The second piece of information is that to retrieve a value from the compartment
-use `myCompartment.get()`. These methods to get and set data inside a
-compartment are the two main pieces to remember.
-
-## Technical information
-
-The follow sections are devoted to more technical information regarding how a
-compartment functions in the broader scope of ngcsimlib and how to leverage that
-information.
-
-### How data is stored
-
-The data stored inside a compartment is not actually stored inside a
-compartment. Instead, it is stored inside the global state and each compartment
-just holds the path or `key`, in the global state to pull a specific piece of
-information. As such it is technically possible to manipulate the value of a
-compartment without actually touching the compartment object created in a
-component. By default, compartments have safeguards to prevent this from happening
-accidentally but directly addressing the compartment in the global state has no
-such safeguards.
-
-### What is targeting
-
-As discussed in the model building section there is a concept of wiring together
-different compartments of different components. These wires are created through
-the concept of targeting. In esscence targeting is just updating the path stored
-in a compartment with the path of a different compartment. This means that if
-the targeted compartment goes to retireve the value stored in it, it will
-actually retrieve the value for the a different compartment. When a compartment
-is in this state where it is targeted at another compartment it is set to read
-only meaning that it can not modify a different compartment.
+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: 
+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 
+   `myCompartment = newValue` becomes `myCompartment.set(newValue)`.
+2. In order to retrieve a value from a compartment, use `myCompartment.get()`. These methods of getting and setting 
+   data inside a compartment are important to use when both working with and designing a multi-compartment component 
+   (i.e., `Component`).
+
+## 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.
+
+### How Data is Stored (Within a Model Context)
+
+The data stored inside of a compartment is not actually physically stored within a compartment. Instead, it is stored 
+inside of the global state and each compartment effectively holds the path or `key` to the right spot in the global 
+state, allowing it to pull out a specific piece of information. As such, it is technically possible to manipulate the 
+value of a compartment without actually touching the compartment object itself within any given component. By default, 
+compartments have in-built safeguards in order to prevent this from happening accidentally; however, directly addressing 
+the compartment within the global state directly has no such safeguards.
+
+### What is "Targeting"?
+
+As discussed in the model building section, there is notion of "wiring" together different compartments of different 
+components -- this is at the core of NGC-Learn's and NGC-Sim-Lib's "nodes-and-cables system". These wires are created 
+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 
+it cannot modify a different compartment.
 
 

docs/compiling.md

@@ -1,35 +1,48 @@
 # Compiling
-The term compiling for ngcsimlib refers to automatic step that happens inside a context that produces a transformed method for all of its components. This step is the most complecated part of the library and generally does not need to be touched or interacted with. Nevertheless this section will cover all the steps that it does at a high level. There is an expectation that the reader has an understanding of python abstract syntax trees, globals, and how to dynamically compile python code to run.
 
-## The decorator
-In ngcsimlib there is a decorator marked as `@compilable` that is used to add a flag to methods that the user wants to compile. On its own it doesn't do anything but this lets the parser distinguish between method that should be compiled and methods that should be ignored.
+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.
 
-## Step by Step
-The process started by telling the parser to compile a specific object.
+## 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).
+
+## 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 the compilable objects of the top level object are compiled. So it loops through all the whole object and compiles each part that it finds that is flagged as compilable and is 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 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.
 
 ### Step 2: Extract Methods to Compile
-While the parser is looping through all the parts of the top level object it is also extracting the methods on the object that are flagged as compilable with the decorator. It stores them for later but this lets the parser 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). ngcsimlib stores them for later; however, this lets the parser know to only loop over the object once.
 
 ### Step 3: Parse Each Method
-As each method is its own entry point into the compiler the step will run for each method in the top level object
 
-### Step 3a: Set up Transformer
-The step sets up a ContextTransformer which is a ask.NodeTransformer and will convert the method from a class method with the use of `self` and other methods that need to be removed into their more context friendly counterpart.
+As each method is its own entry-point into the compiler, this step will run for each method in the top-level object. 
+
+### Step 3a: Set up a Transformer
 
-### 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 compartment's `.get` and `.set` calls are replaced with direct setting and getting from the global state based on the compartment's target. It also means that all temporally constant values such as `batch_size` are moved into the globals space for that specific file and replaced with the naming convention of `object_path_constant`. One more step that this does is ensure that there is no branching in the code. Specifically if there is a brach such as an if statement it will evaluate it and only keep the branch it will traverse down. This means that there can not be any branch logic based on inputs or computed values (this is a common restriction for just in time compiling). 
+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.
+
+### 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). 
 
 ### Step 3c: Parse Sub-Methods
-As it is possible to have other class methods that are not marked as entry points for compilation but need to be compiled as step 3b happens it tracks all the sub-methods needed, this step goes through and repeats steps 3a and 3b for each of them with a naming convention similar to the temporally constant values for each method.
 
-### Step 3d: Compile the AST
-Once we have all the needed namespace and globals needed to execute the method properly transformed the method is compiled with python and executed.
+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.
+
+### 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.
 
 ### Step 3e: Binding
-The final step per method is to bind it to the original method, this replaces the method with an object which when called with act like the normal uncompiled version but has the addition of the `.compiled` attribute which contains all the compiled information to be used later. This allows for the end user to call `myComponent.myMethod.compiled()` and have it run. The exact type for `compiled` value can be found in `ngcsimlib._src.parser.utils:CompiledMethod`.
 
-### Step 4: Finishing Up
-Some objects such as the processes have more steps to modify themselves or their compiled methods to align themselves with needed functionality but that is found in each class's expanded `compile` method and should be referred to by looking at those methods specifically.    
+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.   
+ 

docs/components.md

@@ -1,31 +1,32 @@
 # Components
 
-Living one step above compartments in a model hierachy rests the component. The
-components hold a collection of both temporally constant values and dynamic
-compartments, in addition they are the lowest place where logic governing the
-dynamics of a system are defined. Generally components are going to be the
-building blocks that are reused multiple times throughout a model to create a
-final dynmical system.
+Living one step above compartments in the NGC-Learn dynamical systems hierachy rests the component. 
+A component (`ngcsimlib.Component`) holds a collection of both temporally constant values as well as dynamic (time-evolving) 
+compartments. In addition, they are the core place where logic governing the dynamics of a system are 
+defined. Generally, components serve as the building blocks that are to be reused multiple times 
+when constructing a complete model of a dynmical system.
 
-## Temporally Constant vs Dynamic Compartments
+## Temporally Constant versus Dynamic Compartments
 
-One important distinction that needs to be highlighted inside a component is the
-difference between a temporally constant value and a dynamic compartment.
-Starting with compartments these values that change over time, generally they
-will have the type `ngcsimlib.Compartment` and be used to track internal values
-of the component. These values can be ones such inputs, decaying values,
-counters, etc. The second catagory of values are temporally constant, these are
-values that will remain fixed on the model is constructed. These values tend to
-include ones such as matrix shapes and coefficients.
+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.
+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 
+and meta-parameter settings, such as matrix shapes and coefficients.
 
 ## Defining Compilable Methods
 
-Inside a component it is expected that there are methods used to govern the
-temporal dynamics of a system. These compilable methods are decorated
-with `@compilable` and are defined like any regular method. Inside a compilable
-method there will be access to `self`, meaning that to reference a compartment's
-value it is `self.myCompartment.get()`. The only requirement is that any method
-decorated can not have a return value, values should be stored inside their
-respective compartments. In an external step from defining the component a
-transformer will change all of these methods into ones that function with the
-rest of ngcsimlib.
+Inside of a component, it is expected that there will be methods defined that govern the
+temporal dynamics of the system component. These compilable methods are decorated 
+with `@compilable` and are defined like any other regular (Python) method. Within a compilable
+method, there will be access to `self`, which means that, to reference a compartment's
+value, one must write out such a call as: `self.myCompartment.get()`. The only requirement is 
+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.