some docs on avoiding cycles

doc/create_model.rst

@@ -241,6 +241,16 @@ In terms of computation and inputs, ``advect_model`` is equivalent to the
 ``advect_model_raw`` instance created above ; it is just organized
 differently.
 
+Avoiding cycles in the model
+----------------------------
+Often, a process involves updating a variable, that is used by other processes in the model.
+This may result in a cycle being detected, and the model not able to run. The
+process order is created based on variables with ``intent='out'``. Therefore, any variable 
+that is created with ``intent='inout'`` will be set last in the calculation order. 
+Any process that uses this variable as an input, will use the veriable from the previous timestep. 
+For example, the ``u`` variable in ``ProfileU`` has ``intent='inout'``, and is therefore last in the calculation order.
+
+
 Update existing models
 ----------------------
 

doc/framework.rst

@@ -273,7 +273,9 @@ in their computation.
 In a model, the processes and their dependencies together form the
 nodes and the edges of a Directed Acyclic Graph (DAG). The graph
 topology is fully determined by the ``intent`` set for each variable
-or foreign variable declared in each process. An ordering that is
+or foreign variable declared in each process. That is, a process depends on
+another process if and only if the 'parent' process has an ``intent='out'``
+variable, that is used by the 'child' process. An ordering that is
 computationally consistent can then be obtained using topological
 sorting. This is done at Model object creation. The same ordering is
 used at every stage of a model run.