Technical Documentation¶
This is the technical documentation page. See Tutorials to get started.
Properties¶

afv_grid.
diffusion
¶ Type: num_e
\(\times 1\) vector of doublesDescription: Diffusion across the given edge. It is set by the users before computing transition matrices

afv_grid.
drift
¶ Type: num_e
\(\times 1\) vector of doublesDescription: Drift across the given edge. It is set by the users before computing transition matrices

afv_grid.
e2bd
¶ Type: ( num_e
\(\times\) (2 \(\cdot\)afv_grid.n_dim
))matrix of doublesDescription: Boundary values of edges Note: boundaries are stacked in lexicographic order of (coordinate direction, left/right boundary)

afv_grid.
e2dir
¶ Type: ( num_e
\(\times 1\))vector of integersDescription: Normal/coordinate direction of the edge

afv_grid.
e2n
¶ Type: ( num_e
\(\times\) 2)matrix of integersDescription: Connectivity graph from edges to nodes

afv_grid.
e_weights
¶ Type: ( num_e
\(\times 1\))vector of doublesDescription: (integral) weights of the edges

afv_grid.
n2bd
¶ Type: ( afv_grid.num_e
\(\times\) (2 \(\cdot\)afv_grid.n_dim
) )matrix of doublesDescription: Boundary values of the cell Note: boundaries are stacked in lexicographic order of (left/right boundary, coordinate direction)

afv_grid.
n2e
¶ Type: ( afv_grid.num_e
\(\times\)afv_grid.n_dim
\(\times 2\)) cell array of vector of integersDescription: Connectivity graph from nodes to edges.

afv_grid.
n2n
¶ Type: Description: Neighbor structure of nodes. The third index corresponds to
 1: left neighbors
 2: right neighbors

afv_grid.
n_dim
¶ Type: integer Description: Dimensionality of the grid

afv_grid.
n_points
¶ Type: integer Description: Total number of nodes Warning: This is DEPRECATED, and will be eventually removed. Kept for codereusability with Mean Field Games Toolbox. Use num_e
ornum_n
instead.

afv_grid.
num_e
¶ Type: integer Description: Total number of edges

afv_grid.
num_n
¶ Type: integer Description: Total number of nodes

afv_grid.
num_nb
¶ Type: Description: Number of neighbors of nodes. The third index corresponds to
 1: left neighbors
 2: right neighbors
Functions¶

afv_grid.
add_new_nodes
(obj, n2bd_new, ind_to_consider, flag_compute_left)¶ Add new nodes to the grid
Parameters:  n2bd_new – boundaries of new node points
 ind_to_consider (vector of indices) – (optional) indices of nodes that have interface with new nodes
 flag_compute_left (bool) – (default: false) whether to compute left neighbors as well.
Returns: [n2n] (implicit in class)
 n2n : (in class) neighbor structure
Note
The computing neighbor structure from scratch is an expensive operation. Therefore, one should use new_ind whenever possible. This behavior is guaranteed if one computes using
split_init
orsplit
, so one should use that function whenever it is feasible.

afv_grid.
afv_grid
(n_dim)¶ Empty Constructor
Parameters: n_dim (integer) – Dimensionality of the grid See also

afv_grid.
compute_diffusion_distance
(obj, ind)¶ INTERNAL METHOD: Calculate the diffusion distance to approximate \(\frac{dg}{dx}\) for diffusion in finite volume method
Parameters: ind (vector of indices) – indices of the node to compute the diffusion distance Returns: the distance to be used in diffusion computation. Return type: r_dist (vector of doubles)

afv_grid.
compute_edge_midpoints
(obj, ind, dir, is_left_edge)¶ Compute the midpoint of the given edge of a node
Parameters:  ind (nvector of indices) – indices of the node to compute the midpoint of the edge
 dir (nvector of integers) – coordinate direction of the edge to consider
 is_left_edge (nvector of bools) – whether computing the midpoints of the left edge or not
Returns: midpoints of the edge
Return type: midpts (n \(\times\)
n_dim
of doubles)Note
This function is to calculate external edges of the node that does not face a different node. For internal nodes, consider using function
edge_midpoints

afv_grid.
compute_node_bds
(obj, x_knots)¶ INTERNAL FUNCTION: computes boundaries of new nodes
Parameters: x_knots (cell of vector of doubles) – the boundary knots that define the tensor cut split of a node Returns: boundaries of the nodes Return type: output (matrix of doubles)

afv_grid.
compute_num_neighbors
(obj)¶ Compute the number of neighbors
Parameters: n2n – (implicit) n2n
Returns: [num_nb] implicit in class

afv_grid.
compute_transition_matrix_boundary
(obj, ind, dir, flow, is_left_edge)¶ Compute the transition matrix corresponding to the boundary of the given node
Parameters:  ind (vector of indices) – indices of the node to compute the edge dynamics
 dir (vector of integers) – coordinate directions of the edges/flows to consider
 flow (vector of doubles) – flow/drift rate across the edges
 is_left_edge (vector of bool) – whether the edge is a left edge or not
Returns: the transition matrix of the FPKequation for the given flows across the edges.
Return type: Note
There is
compute_transition_matrix_modified
function that handles the construction of the transition matrix for internal edges facing other cells. This function is supposed to be used for creating the flows for the boundary conditions.

afv_grid.
compute_transition_matrix_center
(obj)¶ Compute the transition matrix corresponding to the Fokker Planck equation
\[\frac{dg}{dt} = \frac{d}{dx}\left(s(x)\cdot g(x)\right) + \nu \frac{d^2 g}{dx^2}\]using central difference approximation.
Parameters:  e2n – implicit in class
 drift – implicit in class
 diffusion – implicit in class
 node_weights – implicit in class
 e_weights – implicit in class
Returns: the transition matrix from the FPKequation
Return type: Note
 Many separate parts are needed before this function can be called properly. Instead of setting them manually, try to use the given functions that guarantee the internal structure.
 This function is for internal edges, for external edges, use
compute_transition_matrix_boundary
.  Central value approximation is not guaranteed to be stable, if the solution do not behave well consider using
compute_transition_matrix_modified
.

afv_grid.
compute_transition_matrix_modified
(obj, weighter)¶ Compute the transition matrix corresponding to the FokkerPlanck equation
\[\frac{dg}{dt} = \frac{d}{dx}\left(s(x)\cdot g(x)\right) + \nu \frac{d^2 g}{dx^2}\]using the modified upwind scheme (equation 2.3) of [Axelsson & Gustafsson, 1979].
Parameters:  e2n – implicit in class
 drift – implicit in class
 diffusion – implicit in class
 node_weights – implicit in class
 e_weights – implicit in class
Returns: the transition matrix from the FPKequation
Return type: Note
 Many separate parts are needed before this function can be called properly. Instead of setting them manually, try to use the given functions that guarantee the internal structure.
 This function is for internal edges, for external edges, use
compute_transition_matrix_boundary
.
References

afv_grid.
compute_transition_matrix_upwind
(obj)¶ Compute the transition matrix corresponding to the Fokker Planck equation
\[\frac{dg}{dt} = \frac{d}{dx}\left(s(x)\cdot g(x)\right) + \nu \frac{d^2 g}{dx^2}\]using upwind approximation.
Parameters:  e2n – implicit in class
 drift – implicit in class
 diffusion – implicit in class
 node_weights – implicit in class
 e_weights – implicit in class
Returns: the transition matrix from the FPKequation
Return type: Warning
Upwind introduced numerical diffusion, so the solution is not accurate compared to other methods. Use
compute_transition_matrix_modified
unless there is a strong reason to use the upwind scheme.Note
 Many separate parts are needed before this function can be called properly. Instead of setting them manually, try to use the given functions that guarantee the internal structure.
 This function is for internal edges, for external edges, use
compute_transition_matrix_boundary
.

afv_grid.
edge_midpoints
(obj, ind)¶ Compute midpoints of the edges
Parameters: ind (vector of indices) – indices of the edges to compute the midpoints Returns: midpoints of the edges Return type: e_midpoints (vector of doubles) See also

afv_grid.
edge_weights
(obj, ind)¶ Compute weight of the given edge
Parameters: ind (vector of indices) – indices of the edges to compute the surface area Returns: surface area of the edges Return type: e_weight (vector of doubles)

afv_grid.
extract_edges
(obj)¶ Extract edges from nodal connections. This function only finds internal edges
Parameters: Returns: [e2bd, e2n, e2dir, e_weights, num_e] (implicit in class)
 e2bd : (in class) boundaries of the edges
 e2n : (in class) connectivity of the edges to the nodes
 e2dir : (in class) normal direction of the edge
 e_weights : (in class) surface area of the edge
 num_e : (in class) total number of edges

afv_grid.
find_neighbor
(obj, ind, dir, is_left, varargin)¶ Find the neighboring node for the given (single) node
Parameters:  ind (integer) – index of the node to find the neighbors of
 dir (integer) – direction to find the neighbors in
 is_left (bool) – whether to look for left neighbors or not
 varargin{1} (vector of indices) – indices of nodes to consider for neighbors (assumed unique)
 n2bd – (implicit in class)
n2bd
 n_dim – (implicit in class)
n_dim
Returns: nbs (vector of indices): indices of the neighbors
Note
find_neighbor_structure()
runs this function for all nodes.

afv_grid.
find_neighbor_structure
(obj, new_ind, flag_compute_left)¶ Construct neighbor structure
Parameters:  new_ind (sorted vector of indices) – (optional) indices of new nodes to append to the neighbor structure
 flag_compute_left (bool) – (default: false) whether to compute left neighbors as well
Returns: [n2n] (implicit in class)
 n2n : (in class) neighbor structure
Note
The computing neighbor structure from scratch is an expensive operation. Therefore, one should use new_ind whenever possible. This behavior is guaranteed if one computes using
split_init
orsplit
, so one should use that function whenever it is feasible.

afv_grid.
node_midpoints
(obj, ind)¶ Compute midpoints of the nodes
Parameters: ind (vector of indices) – (default: ‘:’) indices of the nodes to compute the midpoints Returns: n_midpoints (vector of doubles): midpoints of the nodes

afv_grid.
node_weights
(obj, ind)¶ Compute the weight of the given node
Parameters: ind (vector of indices) – indices of the nodes to compute the volume Returns: volume of the nodes Return type: n_weight (vector of doubles)

afv_grid.
set_dim
(obj, n)¶ Sets dimensionality of the problem. This function works as the initializer for the class
Parameters: n (int) – dimensionality of the problem Returns: (implicit in class) Note
Due to objectoriented design, the set of codes assumes a certain internal consistency of states. Hence, one should always set dimentionality of the problem through
set_dim
.

afv_grid.
split
(obj, ind, x_cuts, flag_compute_left)¶ Split nodes
Parameters:  ind (vector of indices) – indices of the nodes to split
 x_cuts (cell of vector of double) – for each (node, dimension) the cut points to split the node
 flag_compute_left (bool) – (default: false) whether to compute left neighbors as well
Returns: updates all node structure and edge structure of the grid

afv_grid.
split_init
(obj, node_ind, x_cuts)¶ Split a given node which is a starting point
Parameters:  node_ind (integer) – index of the cell to split
 x_cuts (cell of vectors) – points to introduce new edges
Returns: (implicit in class) internally update states to introduce new cells for the given cell