..
   NOTE: The files `landlab.grid.[base|raster|voronoi|radial|hex].rst` are all
   *AUTOGENERATED* from the files `text_for_XXXX.py.txt`! All changes to the
   rst files will be PERMANENTLY LOST whenever the documentation is updated.
   Make changes directly to the txt files instead.

..  _Network:

General class methods and attributes of the `landlab.grid.network` module
------------------------------------------------------------------------

Landlab's network grids are implemented by the class `NetworkModelGrid`,
which inherits from `Graph` and `GraphFields`. This text lists grid methods
available for the class:

Getting Information about a Grid
--------------------------------
The following attributes, properties, and methods provide data about a
NetworkModelGrid, its geometry, and the connectivity among the various elements.
Each grid element has an ID number, which is also its position in an array that
contains information about that type of element. For example, the *x*
coordinate of node 5 would be found at `grid.node_x[5]`.

The naming of grid-element arrays is *attribute*`_at_`*element*, where
*attribute* is the name of the data in question, and *element* is the element
to which the attribute applies. For example, the property `nodes_at_link`
contains the ID of the nodes associated with each link. For example,
`nodes_at_link[3]` contains the *node ID* of the node associated with link 3.
The *attribute* is singular if there is only one value per element; for
example, there are two nodes associated with each link. It is plural when
there are multiple values per element. Exceptions to these general rules are
functions that return indices of a subset of all elements of a particular type.
For example, you can obtain an array with IDs of only the core nodes using
`core_nodes`, while `active_links` provides an array of IDs of active links
(only). Finally, attributes that represent a measurement of something, such as
the length of a link or the surface area of a cell, are described using `_of_`,
as in the example `area_of_cell`.

Information about the grid as a whole
+++++++++++++++++++++++++++++++++++++

LLCATKEY: GINF
Information about nodes
+++++++++++++++++++++++

LLCATKEY: NINF
Information about links
+++++++++++++++++++++++

LLCATKEY: LINF
Data Fields in ModelGrid
------------------------
:class:`~.ModelGrid` inherits from the :class:`~.GraphFields` class. This
provides `~.ModelGrid`, and its subclasses, with the ability to, optionally,
store data values that are associated with the different types grid elements
(nodes, cells, etc.). In particular, as part of ``GraphFields.__init__()``,
data field *groups* are added to the `GraphFields` that provide containers to
put data fields into. There is one group for each of the two grid elements
(node and link).

To access these groups, use the same methods as accessing groups with
`~.GraphFields`. ``GraphFields.__init__()`` adds the following attributes to
itself that provide access to the values groups:

.. autosummary::
    :toctree: generated/
    :nosignatures:

    ~landlab.grid.network.NetworkModelGrid.at_node
    ~landlab.grid.network.NetworkModelGrid.at_link

Each of these attributes returns a ``dict``-like object whose keys are value
names as strings and values are numpy arrays that gives quantities at
grid elements.


Create Field Arrays
+++++++++++++++++++
:class:`~.ModelGrid` inherits several useful methods for creating new data
fields and adding new data fields to a ModelGrid instance. Methods to add or
create a new data array follow the ``numpy`` syntax for creating arrays. The
folowing methods create and, optionally, initialize new arrays. These arrays
are of the correct size but a new field will not be added to the field:

.. autosummary::
    :toctree: generated/
    :nosignatures:

    ~landlab.field.grouped.ModelDataFields.empty
    ~landlab.field.grouped.ModelDataFields.ones
    ~landlab.field.grouped.ModelDataFields.zeros

Add Fields to a ModelGrid
+++++++++++++++++++++++++
Unlike with the equivalent numpy functions, these do not take a size argument
as the size of the returned arrays is determined from the size of the
ModelGrid. However, the keyword arguments are the same as those of the numpy
equivalents.

The following methods will create a new array and add a reference to that
array to the ModelGrid:

.. autosummary::
    :toctree: generated/
    :nosignatures:

    ~landlab.grid.raster.RasterModelGrid.add_empty
    ~landlab.grid.raster.RasterModelGrid.add_field
    ~landlab.grid.raster.RasterModelGrid.add_ones
    ~landlab.grid.raster.RasterModelGrid.add_zeros
    ~landlab.grid.raster.RasterModelGrid.delete_field
    ~landlab.grid.raster.RasterModelGrid.set_units

These methods operate in the same way as the previous set except that, in
addition to creating a new array, the newly-created array is added to the
ModelGrid. The calling signature is the same but with the addition of an
argument that gives the name of the new field as a string. The additional
method, :meth:`~.GraphFields.add_field`, adds a previously allocation
array to the ModelGrid. If the array is of the incorrect size it will raise
``ValueError``.

Query Fields
++++++++++++
Use the following methods/attributes get information about the stored data
fields:

.. autosummary::
    :toctree: generated/
    :nosignatures:

    ~landlab.field.grouped.ModelDataFields.size
    ~landlab.field.grouped.ModelDataFields.keys
    ~landlab.field.grouped.ModelDataFields.has_group
    ~landlab.field.grouped.ModelDataFields.has_field
    ~landlab.grid.network.NetworkModelGrid.field_units
    ~landlab.grid.network.NetworkModelGrid.field_values
    ~landlab.field.grouped.ModelDataFields.groups

i.e., call, e.g. mg.has_field('node', 'my_field_name')

Gradients, fluxes, and divergences on the grid
----------------------------------------------

Landlab is designed to easily calculate gradients in quantities across the
grid, and to construct fluxes and flux divergences from them. Because these
calculations tend to be a little more involved than property lookups, the
methods tend to start with `calc_`.

LLCATKEY: GRAD
Mappers
-------

These methods allow mapping of values defined on one grid element type onto a
second, e.g., mapping upwind node values onto links, or mean link values onto
nodes.

LLCATKEY: MAP
Boundary condition control
--------------------------

These are the primary properties for getting and setting the grid boundary
conditions. Changes made to :meth:`~.ModelGrid.status_at_node` and
:meth:`~.ModelGrid.status_at_node` will automatically update the conditions
defined at other grid elements automatically.

LLCATKEY: BC
Identifying node subsets
------------------------

These methods are useful in identifying subsets of nodes, e.g., closest node
to a point; nodes at edges.

LLCATKEY: SUBSET
