Resources class guide improved.

Author: aslan-ng

docs/build/doctrees/api/resource.doctree

@@ -1,11 +1,36 @@
 Resource
 ========
 
-The :class:`piperabm.resource.Resource` class provides a lightweight container
-for resource quantities (food, water, energy) with validation and arithmetic
+Resources may be provided as plain dictionaries (default) or as instances of the optional :class:`piperabm.resource.Resource` helper class.
+This class provides a lightweight container for resource quantities (food, water, energy) with validation and arithmetic
 support. It is an optional convenience wrapper; internally, PiperABM stores
 resources as plain dictionaries attached to NetworkX graph nodes.
 
+.. code-block:: python
+
+   from piperabm.resource import Resource
+
+   model.society.add_agent(resources=Resource(food=1, water=2, energy=3))
+   # An alternative to:
+   model.society.add_agent(resources={"food":1, "water":2, "energy":3})
+
+.. code-block:: python
+
+   # Retrive resources as a Resource object
+   resources = model.society.get_resources(id=0, object=True)
+   # Retrive resources as a dictionary
+   resources = model.society.get_resources(id=0)
+
+Since the Resource class supports arithmetic operations, it can be used to easily manipulate resource quantities.
+
+.. code-block:: python
+
+   # Retrive resources as a Resource object
+   resources = model.society.get_resources(id=0, object=True)
+   resources =* 2  # Multiply all resource quantities by 2
+   resources =+ Resource(food=1)  # Add 1 unit of food
+   resources =- {"water": 1}  # Subtract 1 unit of water
+
 .. autoclass:: piperabm.resource.Resource
    :members:
    :undoc-members:

docs/build/doctrees/environment.pickle

@@ -137,6 +137,7 @@ To build the infrastructure, we can either manually add elements:
    **Figure 2:** An example of automatically generated infrastructure, after the baking process. The grid is created with some imperfections, and a market node is added to the center of the environment and the homes are randomly placed. The figure is borrowed from `Automatic Creation <https://github.com/cmudrc/pied-piper/blob/main/examples/automatic-creation>`_ example.
 
 For further details on how to load infrastructure using satellite data and maps, refer to the :ref:`Working with Satellite Data <working-with-satellite-data>`.
+Resources may be provided as plain dictionaries (default) or as instances of the optional Resource helper class; see the API reference for details.
 Before continuing to the next step, we need to "bake" the infrastructure. The process of baking finalizes the infrastructure setup that involves applying certain graph grammars to create a physically sensinble network. For more information, please visit :meth:`~piperabm.Model.bake`.
 
 .. note::
@@ -274,6 +275,7 @@ The other method is to automatically generate the society. The generator method
         average_balance=1000,
     )
 
+Resources may be provided as plain dictionaries (default) or as instances of the optional Resource helper class; see the API reference for details.
 Agents use OODA loop, which stands for Observe, Orient, Decide, and Act as the decision-making framework. Agents observe themselves, others, and their environment, and then analyze that information using their values. The result of this decision-making a set of action, that, once executed, will impact the agents and their environment. This loop continues as long as the agetns are alive.
 
 .. figure:: _static/step-by-step/ooda.png

docs/build/doctrees/step-by-step.doctree

@@ -35,10 +35,31 @@
 
   <section id="resource">
 <h1>Resource<a class="headerlink" href="#resource" title="Link to this heading">¶</a></h1>
-<p>The <a class="reference internal" href="#piperabm.resource.Resource" title="piperabm.resource.Resource"><code class="xref py py-class docutils literal notranslate"><span class="pre">piperabm.resource.Resource</span></code></a> class provides a lightweight container
-for resource quantities (food, water, energy) with validation and arithmetic
+<p>Resources may be provided as plain dictionaries (default) or as instances of the optional <a class="reference internal" href="#piperabm.resource.Resource" title="piperabm.resource.Resource"><code class="xref py py-class docutils literal notranslate"><span class="pre">piperabm.resource.Resource</span></code></a> helper class.
+This class provides a lightweight container for resource quantities (food, water, energy) with validation and arithmetic
 support. It is an optional convenience wrapper; internally, PiperABM stores
 resources as plain dictionaries attached to NetworkX graph nodes.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">piperabm.resource</span><span class="w"> </span><span class="kn">import</span> <span class="n">Resource</span>
+
+<span class="n">model</span><span class="o">.</span><span class="n">society</span><span class="o">.</span><span class="n">add_agent</span><span class="p">(</span><span class="n">resources</span><span class="o">=</span><span class="n">Resource</span><span class="p">(</span><span class="n">food</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">water</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">energy</span><span class="o">=</span><span class="mi">3</span><span class="p">))</span>
+<span class="c1"># An alternative to:</span>
+<span class="n">model</span><span class="o">.</span><span class="n">society</span><span class="o">.</span><span class="n">add_agent</span><span class="p">(</span><span class="n">resources</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;food&quot;</span><span class="p">:</span><span class="mi">1</span><span class="p">,</span> <span class="s2">&quot;water&quot;</span><span class="p">:</span><span class="mi">2</span><span class="p">,</span> <span class="s2">&quot;energy&quot;</span><span class="p">:</span><span class="mi">3</span><span class="p">})</span>
+</pre></div>
+</div>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Retrive resources as a Resource object</span>
+<span class="n">resources</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">society</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="nb">object</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+<span class="c1"># Retrive resources as a dictionary</span>
+<span class="n">resources</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">society</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>Since the Resource class supports arithmetic operations, it can be used to easily manipulate resource quantities.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Retrive resources as a Resource object</span>
+<span class="n">resources</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">society</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="nb">object</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+<span class="n">resources</span> <span class="o">=*</span> <span class="mi">2</span>  <span class="c1"># Multiply all resource quantities by 2</span>
+<span class="n">resources</span> <span class="o">=+</span> <span class="n">Resource</span><span class="p">(</span><span class="n">food</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>  <span class="c1"># Add 1 unit of food</span>
+<span class="n">resources</span> <span class="o">=-</span> <span class="p">{</span><span class="s2">&quot;water&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">}</span>  <span class="c1"># Subtract 1 unit of water</span>
+</pre></div>
+</div>
 <dl class="py class">
 <dt class="sig sig-object py" id="piperabm.resource.Resource">
 <em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">piperabm.resource.</span></span><span class="sig-name descname"><span class="pre">Resource</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">food</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">water</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">energy</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#piperabm.resource.Resource" title="Link to this definition">¶</a></dt>

docs/build/html/_sources/api/resource.rst.txt

@@ -154,6 +154,7 @@
 </figcaption>
 </figure>
 <p>For further details on how to load infrastructure using satellite data and maps, refer to the <a class="reference internal" href="satellite.html#working-with-satellite-data"><span class="std std-ref">Working with Satellite Data</span></a>.
+Resources may be provided as plain dictionaries (default) or as instances of the optional Resource helper class; see the API reference for details.
 Before continuing to the next step, we need to “bake” the infrastructure. The process of baking finalizes the infrastructure setup that involves applying certain graph grammars to create a physically sensinble network. For more information, please visit <a class="reference internal" href="api/model.html#piperabm.Model.bake" title="piperabm.Model.bake"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bake()</span></code></a>.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
@@ -272,7 +273,8 @@
 <span class="p">)</span>
 </pre></div>
 </div>
-<p>Agents use OODA loop, which stands for Observe, Orient, Decide, and Act as the decision-making framework. Agents observe themselves, others, and their environment, and then analyze that information using their values. The result of this decision-making a set of action, that, once executed, will impact the agents and their environment. This loop continues as long as the agetns are alive.</p>
+<p>Resources may be provided as plain dictionaries (default) or as instances of the optional Resource helper class; see the API reference for details.
+Agents use OODA loop, which stands for Observe, Orient, Decide, and Act as the decision-making framework. Agents observe themselves, others, and their environment, and then analyze that information using their values. The result of this decision-making a set of action, that, once executed, will impact the agents and their environment. This loop continues as long as the agetns are alive.</p>
 <figure class="align-center" id="id7">
 <img alt="OODA loop as the core decision-making framework." src="_images/ooda.png" />
 <figcaption>

docs/build/html/_sources/step-by-step.rst.txt

@@ -1,11 +1,36 @@
 Resource
 ========
 
-The :class:`piperabm.resource.Resource` class provides a lightweight container
-for resource quantities (food, water, energy) with validation and arithmetic
+Resources may be provided as plain dictionaries (default) or as instances of the optional :class:`piperabm.resource.Resource` helper class.
+This class provides a lightweight container for resource quantities (food, water, energy) with validation and arithmetic
 support. It is an optional convenience wrapper; internally, PiperABM stores
 resources as plain dictionaries attached to NetworkX graph nodes.
 
+.. code-block:: python
+
+   from piperabm.resource import Resource
+
+   model.society.add_agent(resources=Resource(food=1, water=2, energy=3))
+   # An alternative to:
+   model.society.add_agent(resources={"food":1, "water":2, "energy":3})
+
+.. code-block:: python
+
+   # Retrive resources as a Resource object
+   resources = model.society.get_resources(id=0, object=True)
+   # Retrive resources as a dictionary
+   resources = model.society.get_resources(id=0)
+
+Since the Resource class supports arithmetic operations, it can be used to easily manipulate resource quantities.
+
+.. code-block:: python
+
+   # Retrive resources as a Resource object
+   resources = model.society.get_resources(id=0, object=True)
+   resources =* 2  # Multiply all resource quantities by 2
+   resources =+ Resource(food=1)  # Add 1 unit of food
+   resources =- {"water": 1}  # Subtract 1 unit of water
+
 .. autoclass:: piperabm.resource.Resource
    :members:
    :undoc-members:

docs/build/html/api/resource.html

@@ -137,6 +137,7 @@ To build the infrastructure, we can either manually add elements:
    **Figure 2:** An example of automatically generated infrastructure, after the baking process. The grid is created with some imperfections, and a market node is added to the center of the environment and the homes are randomly placed. The figure is borrowed from `Automatic Creation <https://github.com/cmudrc/pied-piper/blob/main/examples/automatic-creation>`_ example.
 
 For further details on how to load infrastructure using satellite data and maps, refer to the :ref:`Working with Satellite Data <working-with-satellite-data>`.
+Resources may be provided as plain dictionaries (default) or as instances of the optional Resource helper class; see the API reference for details.
 Before continuing to the next step, we need to "bake" the infrastructure. The process of baking finalizes the infrastructure setup that involves applying certain graph grammars to create a physically sensinble network. For more information, please visit :meth:`~piperabm.Model.bake`.
 
 .. note::
@@ -274,6 +275,7 @@ The other method is to automatically generate the society. The generator method
         average_balance=1000,
     )
 
+Resources may be provided as plain dictionaries (default) or as instances of the optional Resource helper class; see the API reference for details.
 Agents use OODA loop, which stands for Observe, Orient, Decide, and Act as the decision-making framework. Agents observe themselves, others, and their environment, and then analyze that information using their values. The result of this decision-making a set of action, that, once executed, will impact the agents and their environment. This loop continues as long as the agetns are alive.
 
 .. figure:: _static/step-by-step/ooda.png