ngcsimlib 0.2b0__tar.gz

ngcsimlib-0.2b0/AUTHORS

@@ -0,0 +1,10 @@
+# This file contains an official list of authors of this framework.
+
+# Names should be added to this file as:
+# Name or Organization <email address>
+# The email address is not required for organizations.
+
+Core Team
+William Gebhardt <wdg1351@rit.edu>
+Alexander Ororbia <ago@cs.rit.edu>
+

ngcsimlib-0.2b0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, The Neural Adaptive Computing Laboratory
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ngcsimlib-0.2b0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.1
+Name: ngcsimlib
+Version: 0.2b0
+Summary: Simulation software backend for ngc-learn.
+Author-email: William Gebhardt <wdg1351@rit.edu>, Alexander Ororbia <ago@cs.rit.edu>
+License: BSD-3-Clause License
+Project-URL: Homepage, https://github.com/NACLab/ngc-sim-lib
+Project-URL: Lab Page, https://www.cs.rit.edu/~ago/nac_lab.html
+Keywords: python,complex-systems,simulation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS
+
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11-blue.svg)](https://www.python.org/downloads)[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/Naereen/StrapDown.js/graphs/commit-activity)
+[![DOI](https://zenodo.org/badge/734040498.svg)](https://zenodo.org/doi/10.5281/zenodo.10888210)
+
+# NGC-Sim-Lib: Support Library for NGC-Learn
+
+<b>ngc-sim-lib</b> is the support library and central dependency for
+<i><a href="https://github.com/NACLab/ngc-learn/">ngc-learn</a></i>, a library
+designed for computational neuroscience and cognitive neuroscience research.
+While ngc-learn contains the JAX-implemented routines and any supporting C
+code, ngc-sim-lib is a pure Python package, primarily meant for providing the
+machinery, routines, and utilities that facilitate the general (abstract)
+simulation of complex adaptive systems made up of dynamical components. For
+information, including anything related to usage instructions and details,
+please refer to the ngc-learn README:
+https://github.com/NACLab/ngc-learn/.
+
+This package is distributed under the 3-Clause BSD license. It is currently
+maintained by the
+<a href="https://www.cs.rit.edu/~ago/nac_lab.html">Neural Adaptive Computing
+(NAC) laboratory</a>.
+
+## <b>Installation:</b>
+
+<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.10)`.
+
+Once you have ensured that the appropriate Python is installed, you can then
+have the <code>ngclib</code> package installed on your system using the
+following bash command:
+<pre>
+$ pip install .
+</pre>
+or, if you are doing development, then do an editable install via:
+<pre>
+$ pip install --editable . # OR pip install -e .
+</pre>
+
+**Version:**<br>
+0.2.0 <!-- -Alpha -->
+
+Authors:
+William Gebhardt, Alexander G. Ororbia II<br>
+Neural Adaptive Computing (NAC) Laboratory<br>
+Rochester Institute of Technology, Department of Computer Science
+
+## <b>Copyright:</b>
+
+Copyright (C) 2023 The Neural Adaptive Computing Laboratory - All Rights Reserved<br>
+You may use, distribute and modify this code under the
+terms of the BSD 3-clause license.
+
+You should have received a copy of the BSD 3-clause license with
+this software.<br>
+If not, please [email us](mailto:ago@cs.rit.edu)

ngcsimlib-0.2b0/README.md

@@ -0,0 +1,55 @@
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11-blue.svg)](https://www.python.org/downloads)[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/Naereen/StrapDown.js/graphs/commit-activity)
+[![DOI](https://zenodo.org/badge/734040498.svg)](https://zenodo.org/doi/10.5281/zenodo.10888210)
+
+# NGC-Sim-Lib: Support Library for NGC-Learn
+
+<b>ngc-sim-lib</b> is the support library and central dependency for
+<i><a href="https://github.com/NACLab/ngc-learn/">ngc-learn</a></i>, a library
+designed for computational neuroscience and cognitive neuroscience research.
+While ngc-learn contains the JAX-implemented routines and any supporting C
+code, ngc-sim-lib is a pure Python package, primarily meant for providing the
+machinery, routines, and utilities that facilitate the general (abstract)
+simulation of complex adaptive systems made up of dynamical components. For
+information, including anything related to usage instructions and details,
+please refer to the ngc-learn README:
+https://github.com/NACLab/ngc-learn/.
+
+This package is distributed under the 3-Clause BSD license. It is currently
+maintained by the
+<a href="https://www.cs.rit.edu/~ago/nac_lab.html">Neural Adaptive Computing
+(NAC) laboratory</a>.
+
+## <b>Installation:</b>
+
+<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.10)`.
+
+Once you have ensured that the appropriate Python is installed, you can then
+have the <code>ngclib</code> package installed on your system using the
+following bash command:
+<pre>
+$ pip install .
+</pre>
+or, if you are doing development, then do an editable install via:
+<pre>
+$ pip install --editable . # OR pip install -e .
+</pre>
+
+**Version:**<br>
+0.2.0 <!-- -Alpha -->
+
+Authors:
+William Gebhardt, Alexander G. Ororbia II<br>
+Neural Adaptive Computing (NAC) Laboratory<br>
+Rochester Institute of Technology, Department of Computer Science
+
+## <b>Copyright:</b>
+
+Copyright (C) 2023 The Neural Adaptive Computing Laboratory - All Rights Reserved<br>
+You may use, distribute and modify this code under the
+terms of the BSD 3-clause license.
+
+You should have received a copy of the BSD 3-clause license with
+this software.<br>
+If not, please [email us](mailto:ago@cs.rit.edu)

ngcsimlib-0.2b0/ngcsimlib/__init__.py

@@ -0,0 +1,50 @@
+from . import utils
+from . import controller
+from . import commands
+
+import argparse, os, warnings, json
+from types import SimpleNamespace
+from pathlib import Path
+from sys import argv
+from importlib import import_module
+
+from pkg_resources import get_distribution
+
+__version__ = get_distribution('ngcsimlib').version ## set software version
+
+###### Preload Modules
+def preload():
+    parser = argparse.ArgumentParser(description='Build and run a model using ngclearn')
+    parser.add_argument("--modules", type=str, help='location of modules.json file')
+
+    args = parser.parse_args()
+    try:
+        module_path = args.modules
+    except:
+        module_path = None
+
+    if module_path is None:
+        module_path = "json_files/modules.json"
+
+    if not os.path.isfile(module_path):
+        warnings.warn("Missing file to preload modules from. Attempted to locate file at \"" + str(module_path) + "\"" )
+        return
+
+    with open(module_path, 'r') as file:
+        modules = json.load(file, object_hook=lambda d: SimpleNamespace(**d))
+
+    for module in modules:
+        mod = import_module(module.absolute_path)
+        utils._Loaded_Modules[module.absolute_path] = mod
+
+        for attribute in module.attributes:
+            atr = getattr(mod, attribute.name)
+            utils._Loaded_Attributes[attribute.name] = atr
+
+            utils._Loaded_Attributes[".".join([module.absolute_path, attribute.name])] = atr
+            if hasattr(attribute, "keywords"):
+                for keyword in attribute.keywords:
+                    utils._Loaded_Attributes[keyword] = atr
+
+if not Path(argv[0]).name == "sphinx-build" or Path(argv[0]).name == "build.py":
+    preload()

ngcsimlib-0.2b0/ngcsimlib/bundle_rules.py

@@ -0,0 +1,64 @@
+"""
+Contains all the built-in bundle rules as well as the default one for an unbundled
+cable. Bundle(s) usage is that it is to be added to a component's bundle rules
+(Note: the overwrite rule is the default rule).
+
+
+Template for bundle rules. The name of the bundle rule should be meaningful to what it does. All bundle rules will
+be called with the same three inputs: component, value, and destination_compartment. These are not passed by keyword but
+they will always be in the same order. The component is the component that the bundle has as a destination (target).
+The value is the signal that goes into (or comes along to) the connected bundle. The destination_compartment is
+the compartment that the bundle is connected to. Overall, the general usage of bundle rules is to modify the
+behavior of an input to a compartment; generally, they should NOT modify any other aspect of the target
+component aside from the destination compartment and, as a warning, should not try to reference compartments by
+name as this will possibly result in runtime errors given that the required compartments for the bundle rule(s)
+might not exist.
+
+General bundle rule specification:
+
+def BUNDLE_RULE_NAME(component, value, destination_compartment):
+    ## Logic for processing transmitted value
+    ## Syntax for referencing destination compartment -> component.compartments[destination_compartment]
+
+"""
+def overwrite(component, value, destination_compartment):
+    """
+    The overwrite bundle rule routine.
+
+    Args:
+        component: target component node that this bundle rule will operate on
+
+        value: the value to insert into a compartment within the target component
+
+        destination_compartment: compartment within component to place a value w/in
+    """
+    component.compartments[destination_compartment] = value
+
+
+def additive(component, value, destination_compartment):
+    """
+    The additive/addition bundle rule routine.
+
+    Args:
+        component: target component node that this bundle rule will operate on
+
+        value: the value to add to current state of compartment w/in target component
+
+        destination_compartment: compartment within component to add a value to
+    """
+    component.compartments[destination_compartment] += value
+
+
+def append(component, value, destination_compartment):
+    """
+    The append/aggregation bundle rule routine. This is primarily useful if
+    the compartment is a list of a values/objects (an appendable list construct).
+
+    Args:
+        component: target component node that this bundle rule will operate on
+
+        value: the value to append to current state of compartment w/in target component
+
+        destination_compartment: compartment within component to append to
+    """
+    component.compartments[destination_compartment].append(value)

ngcsimlib-0.2b0/ngcsimlib/commands/__init__.py

@@ -0,0 +1,11 @@
+from .command import Command
+from .advanceState import AdvanceState
+from .clamp import Clamp
+from .evolve import Evolve
+from .reset import Reset
+from .track import Track
+from .save import Save
+from .compound import Compound
+from .snapshot import Snapshot
+from .multiclamp import Multiclamp
+

ngcsimlib-0.2b0/ngcsimlib/commands/advanceState.py

@@ -0,0 +1,25 @@
+from ngcsimlib.commands import Command
+
+
+class AdvanceState(Command):
+    """
+    As the general form, all models built in ngclearn are state machines and this
+    command is designed to advance the state of all of the components passed into
+    the command. Prior to advancing the state of each component, this will call the
+    `gather` method of that component.
+    """
+    def __init__(self, components=None, command_name=None, **kwargs):
+        """
+        Required calls on Components: ['advance_state', 'gather', 'name']
+
+        Args:
+            components: the list of components to advance the state of
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['advance_state', 'gather'])
+
+    def __call__(self, **kwargs):
+        for component in self.components:
+            self.components[component].gather()
+            self.components[component].advance_state(**kwargs)

ngcsimlib-0.2b0/ngcsimlib/commands/clamp.py

@@ -0,0 +1,58 @@
+from ngcsimlib.commands.command import Command
+from ngcsimlib.utils import extract_args
+
+
+class Clamp(Command):
+    """
+    All components in ngclearn have compartments where they store information
+    pertaining to their internal state that can be read into or out of by
+    commands. The Clamp command is the primary way to manually set the value of
+    a compartment on a set of components. The Clamp command requires a
+    compartment that a value can be passed into and be clamped to,
+    as well as a `clamp_name` used to locate the value when called.
+    """
+
+    def __init__(self, components=None, compartment=None, clamp_name=None,
+                 command_name=None, **kwargs):
+        """
+        Required calls on Components: ['clamp', 'name']
+
+        Args:
+            components: a list of components to call clamp on
+
+            compartment: the compartment being clamped to
+
+            clamp_name: a keyword to bind the input for this command do
+
+            command_name: the name of the command on the controller
+
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['clamp'])
+        if compartment is None:
+            raise RuntimeError(
+                self.name + " requires a \'compartment\' to clamp to for construction")
+        if clamp_name is None:
+            raise RuntimeError(
+                self.name + " requires a \'clamp_name\' to bind to for construction")
+
+        self.clamp_name = clamp_name
+        self.compartment = compartment
+
+        for component in self.components:
+            if self.compartment not in self.components[component].compartments.keys():
+                raise RuntimeError(self.name + " is attempting to "
+                                               "initialize clamp to "
+                                               "non-existent compartment.")
+
+    def __call__(self, *args, **kwargs):
+        try:
+            vals = extract_args([self.clamp_name], *args, **kwargs)
+        except RuntimeError:
+            raise RuntimeError(self.name + ", " + str(
+                self.clamp_name) + " is missing from keyword arguments or a positional "
+                                   "arguments can be provided")
+
+        for component in self.components:
+            self.components[component].clamp(self.compartment, vals[self.clamp_name])
+

ngcsimlib-0.2b0/ngcsimlib/commands/command.py

@@ -0,0 +1,34 @@
+from abc import ABC, abstractmethod
+from ngcsimlib.utils import check_attributes
+
+
+class Command(ABC):
+    """
+    The base class for all commands found in ngcsimlib. At its core, a command is
+    essentially a method to be called by the controller that affects the
+    components in a simulated complex system / model in some way. When a command
+    is made, a preprocessing step is run to verify that all of the needed
+    attributes are present on each component. Note that this step does not
+    ensure types or values, just that they do or do not exist.
+    """
+    def __init__(self, components=None, command_name=None, required_calls=None):
+        """
+        Required calls on Components: ['name']
+
+        Args:
+            components: a list of components to run the command on
+
+            required_calls: a list of required attributes for all components
+
+            command_name: the name of the command on the controller
+        """
+        self.name = str(command_name)
+        self.components = {}
+        required_calls = ['name'] if required_calls is None else required_calls + ['name']
+        for comp in components:
+            if check_attributes(comp, required_calls, fatal=True):
+                self.components[comp.name] = comp
+
+    @abstractmethod
+    def __call__(self, *args, **kwargs):
+        pass

ngcsimlib-0.2b0/ngcsimlib/commands/compound.py

@@ -0,0 +1,39 @@
+from ngcsimlib.commands import Command
+from ngcsimlib.utils import check_attributes
+import warnings
+
+class Compound(Command):
+    """
+    There is sometimes a need by controllers to be able to call a set of commands
+    in series without writing custom command(s) for each combination. The
+    compound node/command is used to fill this need. A compound command set is
+    very similar to the cycle found inside/within a controller / simulation object.
+    """
+    def __init__(self, components=None, command_name=None, command_list=None,
+                 controller=None, **kwargs):
+        """
+        Constructs a compound command construct.
+        
+        Args:
+            components: a list of components, this will go unused by default
+
+            command_name: the name of the compound command
+
+            command_list: a list of all commands to be called
+
+            controller: the controller that will be calling these commands
+        """
+        super().__init__(components=components, command_name=command_name)
+        if controller is None:
+            raise RuntimeError("The controller is needed to build a compound command (This should be passed in by default)")
+        if command_list is None or len(command_list) == 0:
+            warnings.warn("The command list for command " + self.name + " is None or empty")
+
+        self.command_list = command_list
+        self.controller = controller
+
+        check_attributes(self.controller, self.command_list, fatal=True)
+
+    def __call__(self, *args, **kwargs):
+        for command in self.command_list:
+            self.controller.runCommand(command, *args, **kwargs)

ngcsimlib-0.2b0/ngcsimlib/commands/evolve.py

@@ -0,0 +1,41 @@
+from ngcsimlib.commands import Command
+from ngcsimlib.utils import extract_args
+
+class Evolve(Command):
+    """
+    In many models, there is a need to have either a backward pass or a separate
+    method to update some particular internal state (value), e.g., a "learning"
+    or evolutionary change that is not related to central compartment states.
+    In general, this can be mapped to a call of `evolve`. Like with
+    `advanceState`, this will call the gather method prior to calling the
+    `evolve` function of every component.
+
+    """
+    def __init__(self, components=None, frozen_flag=None, command_name=None,
+                 **kwargs):
+        """
+        Required calls on Components: ['evolve', 'gather', 'name']
+
+        Args:
+            components: the list of components to evolve
+
+            frozen_flag: the keyword for the flag to freeze this evolve step
+
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['evolve'])
+
+        self.frozen_flag = frozen_flag
+
+    def __call__(self, *args, **kwargs):
+        vals = {}
+        try:
+            vals = extract_args([self.frozen_flag], *args, **kwargs)
+        except RuntimeError:
+            vals[self.frozen_flag] = False
+
+        if not vals[self.frozen_flag]:
+            for component in self.components:
+                self.components[component].gather()
+                self.components[component].evolve(**kwargs)

ngcsimlib-0.2b0/ngcsimlib/commands/multiclamp.py

@@ -0,0 +1,42 @@
+from ngcsimlib.commands.command import Command
+from ngcsimlib.utils import extract_args, check_attributes
+
+
+class Multiclamp(Command):
+    """
+    There are times when a model will have many clamp calls as there might be a
+    need to clamp many different values to a model at the same time. As a
+    solution to this, ngcsimlib provides the `multiclamp` command. This command is
+    used to set a wide range of values to all compartments with the same name
+    across all provided compartments.
+    """
+
+    def __init__(self, components=None, clamp_name=None, command_name=None,
+                 **kwargs):
+        """
+        Required calls on Components: ['clamp', 'name']
+        Args:
+            components: a list of components to call clamp on
+
+            clamp_name: a keyword to bind the input for this command do
+
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['clamp'])
+        if clamp_name is None:
+            raise RuntimeError(self.name + " requires a \'clamp_name\' to bind to for construction")
+
+        self.clamp_name = clamp_name
+
+    def __call__(self, *args, **kwargs):
+        try:
+            vals = extract_args([self.clamp_name], *args, **kwargs)
+        except RuntimeError:
+            raise RuntimeError(self.name + ", " + str(self.clamp_name) + " is missing from keyword arguments or a "
+                                                                       "positional arguments can be provided")
+
+        for compartment, value in vals[self.clamp_name].items():
+            for component in self.components:
+                if check_attributes(component, compartment, fatal=False):
+                    self.components[component].clamp(compartment, value)

ngcsimlib-0.2b0/ngcsimlib/commands/reset.py

@@ -0,0 +1,40 @@
+from ngcsimlib.commands import Command
+from ngcsimlib.utils import extract_args
+import warnings
+
+class Reset(Command):
+    """
+    In every model/system, there is a need to reset components back to some
+    intial state value(s). As such, many components that maintain a state have a
+    reset method implemented within them. The reset command will go through
+    the list of components and trigger the reset within each of them.
+    """
+    def __init__(self, components=None, reset_name=None, command_name=None,
+                 **kwargs):
+        """
+        Required calls on Components: ['reset', 'name']
+
+        Args:
+            components: a list of components to reset
+
+            reset_name: the keyword for the flag on if the reset should happen
+
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['reset'])
+        if reset_name is None:
+            raise RuntimeError(self.name + " requires a \'reset_name\' to bind to for construction")
+        self.reset_name = reset_name
+
+    def __call__(self, *args, **kwargs):
+        try:
+            vals = extract_args([self.reset_name], *args, **kwargs)
+        except RuntimeError:
+            warnings.warn(self.name + ", " + str(self.reset_name) + " is missing from keyword arguments and no "
+                                                             "positional arguments were provided", stacklevel=6)
+            return
+
+        if vals[self.reset_name]:
+            for component in self.components:
+                self.components[component].reset()

ngcsimlib-0.2b0/ngcsimlib/commands/save.py

@@ -0,0 +1,46 @@
+from ngcsimlib.commands import Command
+from ngcsimlib.utils import extract_args
+import warnings
+
+class Save(Command):
+    """
+    When training models, there is often a need to snapshot the model and save
+    it to disk. The base controller in ngcsimlib is able to save all of the
+    commands, components, connections, and steps to a file in order to rebuild
+    the model at a later time. However, there is a good chance that the model
+    will contain components that have parts that need saving beyond the parameters
+    passed in to initialize the component. ngcsimlib solves this by providing a
+    save command; this command will call a custom save method on all components
+    provided to the command. This custom save method will be responsible for all
+    custom values to be saved and determining where to save them inside of a
+    provided directory.
+    """
+    def __init__(self, components=None, directory_flag=None, command_name=None,
+                 **kwargs):
+        """
+        Required calls on Components: ['save', 'name']
+
+        Args:
+            components: a list of components to call the save function on
+
+            directory_flag: keyword for flag for the directory to save to
+
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=['save'])
+        if directory_flag is None:
+            raise RuntimeError(self.name + " requires a \'directory_flag\' to bind to for construction")
+        self.directory_flag = directory_flag
+
+    def __call__(self, *args, **kwargs):
+        try:
+            vals = extract_args([self.directory_flag], *args, **kwargs)
+        except RuntimeError:
+            warnings.warn(self.name + ", " + str(self.directory_flag) + " is missing from keyword arguments and no "
+                                                                "positional arguments were provided", stacklevel=6)
+            return
+
+        if vals[self.directory_flag]:
+            for component in self.components:
+                self.components[component].save(vals[self.directory_flag])

ngcsimlib-0.2b0/ngcsimlib/commands/snapshot.py

@@ -0,0 +1,39 @@
+from ngcsimlib.commands import Command
+
+class Snapshot(Command):
+    """
+    Sometimes when running through a model, there is a need to extract a value
+    from a compartment to the run loop. As such, ngcsimlib provides the snapshot
+    command. This command will extract a given attribute from all components
+    provided to the command. This command returns a single value if only one
+    component is given, otherwise it will return a list where each value
+    corresponds to the position of the component in the components list.
+
+    This command is regularly used for debugging/graph production code that
+    exists outside of the model. It would be incorrect to clamp the output of
+    this command into another component, if that is the intended goal, please
+    see `connect` in the controller.
+    """
+    def __init__(self, components=None, attribute=None, command_name=None,
+                 **kwargs):
+        """
+        Required calls on Components: ['name'], and the passed-in attribute
+
+        Args:
+            components: the component extract the values of
+
+            attribute: a single attribute to return
+
+            command_name: the name of the command on the controller
+        """
+        super().__init__(components=components, command_name=command_name,
+                         required_calls=[attribute])
+        self.attribute = attribute
+
+
+    def __call__(self, *args, **kwargs):
+        vals = []
+        for component in self.components:
+            vals.append(getattr(self.components[component], self.attribute))
+
+        return vals if len(vals) > 1 else vals[0]