modded docs to include v3 foundations

Author: Alexander Ororbia

docs/tutorials/foundations.md

@@ -3,6 +3,8 @@
 In this set of tutorials/walkthroughs, we go through some of the core elements and mechanisms underlying NGC-Learn in order understand how its simulation scheme (and the nodes-and-cables system) works and to help in writing your own custom elements.
 
 The foundational walkthroughs are organized as follows:
-1. <b>[Using Model Contexts](../tutorials/foundations/contexts.md)</b>: This lesson goes the fundamentals of the primary simulation construct you need to set up models, the (simulation) context.
-2. <b>[Understanding Commands](../tutorials/foundations/commands.md)</b>: This lesson will walk you through the basics of a command -- an essential part of building a simulation controller in ngc-learn and ngcsimlib -- and offer some useful points for designing new ones.
+1. <b>[Using Model Contexts](../tutorials/foundations/context.md)</b>: This lesson goes the fundamentals of the primary simulation construct you need to set up models, the (simulation) context.
+2. <b>[Understanding Processes](../tutorials/foundations/processes.md)</b>: This lesson will walk you through the basics of a command -- an essential part of building a simulation controller in ngc-learn and ngcsimlib -- and offer some useful points for designing new ones.
+<!--
 3. <b>[Operations](../tutorials/foundations/operations.md)</b>: Here, the basics of bundle rules, a commonly-used mechanism for crafting complex biophysical systems, will be presented.
+--> 

docs/tutorials/foundations/commands.md

@@ -0,0 +1,44 @@
+# Compartments
+
+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`.
+
+## Practical Information
+
+Practically, when working with compartments, there are a few simple things to keep in mind despite the fact that most 
+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 
+   `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 NGC-Sim-Lib 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-only, which only means that 
+it cannot modify a different compartment.
+
+

docs/tutorials/foundations/compartments.md

@@ -0,0 +1,98 @@
+# Compiling
+
+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 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 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). 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 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
+`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, 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,
+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.
+
+### 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`.
+
+### 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/tutorials/foundations/compiling.md

@@ -0,0 +1,32 @@
+# Components
+
+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 versus Dynamic Compartments
+
+One important distinction that needs to be highlighted within a component is the 
+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 
+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
+
+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 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.