Add network docs page with classes, restructure docstrings

doc/OnlineDocs/modeling_extensions/index.rst

@@ -9,4 +9,4 @@ Modeling Extensions
    mpec.rst
    gdp.rst
    pysp.rst
-
+   network.rst

doc/OnlineDocs/modeling_extensions/network.rst

@@ -0,0 +1,90 @@
+Pyomo Network
+=============
+
+Pyomo Network is a package that allows users to easily represent their model
+as a connected network of units. Units are blocks that contain ports, which
+contain variables, that are connected to other ports via arcs. The connection
+of two ports to each other via an arc typically represents a set of constraints
+equating each member of each port to each other, however there exist other
+connection rules as well, in addition to support for custom rules. Pyomo
+Network also includes a model transformation that will automatically expand
+the arcs and generate the appropriate constraints to produce an algebraic
+model that a solver can handle. Furthermore, the package also introduces a
+generic sequential decomposition tool that can leverage the modeling
+components to decompose a model and compute each unit in the model in a
+logically ordered sequence.
+
+Modeling Components
+-------------------
+
+Pyomo Network introduces two new modeling components to Pyomo:
+
+.. autosummary::
+    :nosignatures:
+
+    pyomo.network.Port
+    pyomo.network.Arc
+
+Port
+****
+
+.. autoclass:: pyomo.network.Port
+    :members:
+    :exclude-members: construct, display
+
+.. autoclass:: pyomo.network.port._PortData
+    :members:
+    :special-members: __getattr__
+    :exclude-members: set_value
+
+The following code snippet shows examples of declaring and using a
+:py:class:`Port <pyomo.network.Port>` component on a
+concrete Pyomo model:
+
+.. doctest::
+
+   >>> from pyomo.environ import *
+   >>> from pyomo.network import *
+   >>> m = ConcreteModel()
+   >>> m.x = Var()
+   >>> m.y = Var(['a', 'b']) # can be indexed
+   >>> m.z = Var()
+   >>> m.e = 5 * m.z # you can add Pyomo expressions too
+   >>> m.w = Var()
+
+   >>> m.p = Port()
+   >>> m.add(m.x) # implicitly name the port member "x"
+   >>> m.add(m.y, "foo") # name the member "foo"
+   >>> m.add(m.e, rule=Port.Extensive) # specify a rule
+   >>> m.add(m.w, rule=Port.Extensive, write_var_sum=False) # keyword arg
+
+Arc
+***
+
+.. autoclass:: pyomo.network.Arc
+    :members:
+    :exclude-members: construct
+
+.. autoclass:: pyomo.network.arc._ArcData
+    :members:
+    :special-members: __getattr__
+
+The following code snippet shows examples of declaring and using an
+:py:class:`Arc <pyomo.network.Arc>` component on a
+concrete Pyomo model:
+
+.. doctest::
+
+   >>> from pyomo.environ import *
+   >>> from pyomo.network import *
+   >>> m = ConcreteModel()
+   >>> m.x = Var()
+   >>> m.y = Var(['a', 'b'])
+   >>> m.u = Var()
+   >>> m.v = Var(['a', 'b']) # indexes need to match
+
+   >>> m.p = Port(initialize=[m.x, m.y])
+   >>> m.q = Port(initialize={"x": m.u, "y": m.v}) # names need to match
+   >>> m.a = Arc(source=m.p, destination=m.q) # directed
+   >>> m.b = Arc(ports=(m.p, m.q)) # undirected
+   >>> m.c = Arc(ports=(m.p, m.q), directed=True) # directed

pyomo/network/arc.py

@@ -50,7 +50,24 @@ def _iterable_to_dict(vals, directed, name):
 
 
 class _ArcData(ActiveComponentData):
-    """This class defines the data for a single Arc."""
+    """
+    This class defines the data for a single Arc
+
+    Attributes
+    ----------
+        source: `Port`
+            The source Port when directed, else None. Aliases to src.
+        destination: `Port`
+            The destination Port when directed, else None. Aliases to dest.
+        ports: `tuple`
+            A tuple containing both ports. If directed, this is in the
+            order (source, destination).
+        directed: `bool`
+            True if directed, False if not
+        expanded_block: `Block`
+            A reference to the block on which expanded constraints for this
+            arc were placed
+    """
 
     __slots__ = ('_ports', '_directed', '_expanded_block')
 
@@ -81,7 +98,7 @@ def __getstate__(self):
     # can quietly rely on the super() class's implementation.
 
     def __getattr__(self, name):
-        """Returns self.expanded_block.name if it exists"""
+        """Returns `self.expanded_block.name` if it exists"""
         eb = self.expanded_block
         if eb is not None:
             try:
@@ -125,12 +142,7 @@ def expanded_block(self):
         return self._expanded_block
 
     def set_value(self, vals):
-        """
-        Set the port attributes on this arc.
-
-        If these values are being reassigned, note that the defaults
-        are still None, so you may need to repass some attributes.
-        """
+        """Set the port attributes on this arc"""
         # the following allows m.a = Arc(directed=True); m.a = (m.p, m.q)
         # and m.a will be directed
         d = self._directed if self._directed is not None else \
@@ -233,28 +245,22 @@ def _validate_ports(self, source, destination, ports):
 
 class Arc(ActiveIndexedComponent):
     """
-    Component used for connecting the members of two Port objects.
-
-    Constructor arguments:
-        source          A single Port for a directed arc. Aliases to src
-        destination     A single Port for a directed arc. Aliases to dest
-        ports           A two-member list or tuple of single Ports
-                            for an undirected arc
-        directed        True if directed. Use along with rule to be able to
-                            return an implied (source, destination) tuple
-        rule            A function that returns either a dictionary of the
-                            arc arguments or a two-member iterable of ports
-        doc             A text string describing this component
-        name            A name for this component
-
-    Public attributes
-        source          The source Port when directed, else None.
-                            Aliases to src
-        destination     The destination Port when directed, else None.
-                            Aliases to dest
-        ports           A tuple containing both ports. If directed, this
-                            is in the order (source, destination)
-        directed        True if directed, False if not
+    Component used for connecting the members of two Port objects
+
+    Parameters
+    ----------
+        source: `Port`
+            A single Port for a directed arc. Aliases to src.
+        destination: `Port`
+            A single`Port for a directed arc. Aliases to dest.
+        ports
+            A two-member list or tuple of single Ports for an undirected arc
+        directed: `bool`
+            Set True for directed. Use along with `rule` to be able to
+            return an implied (source, destination) tuple.
+        rule: `function`
+            A function that returns either a dictionary of the arc arguments
+            or a two-member iterable of ports
     """
 
     _ComponentDataClass = _ArcData