Technical Documentation¶

This is the technical documentation page. See Tutorials to get started.

Properties¶

afv_grid.diffusion
Type: num_e$$\times 1$$ vector of doubles 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 doubles 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 doubles Boundary values of edges boundaries are stacked in lexicographic order of (coordinate direction, left/right boundary)
afv_grid.e2dir
Type: (num_e$$\times 1$$)-vector of integers Normal/coordinate direction of the edge
afv_grid.e2n
Type: (num_e $$\times$$ 2)-matrix of integers Connectivity graph from edges to nodes
afv_grid.e_weights
Type: (num_e$$\times 1$$)-vector of doubles (integral) weights of the edges
afv_grid.n2bd
Type: (afv_grid.num_e $$\times$$ (2 $$\cdot$$ afv_grid.n_dim ) )-matrix of doubles Boundary values of the cell 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 integers Connectivity graph from nodes to edges.
afv_grid.n2n
Type: (num_n$$\times$$n_dim$$\times 2$$) cell of integers Neighbor structure of nodes. The third index corresponds to 1: left neighbors 2: right neighbors
afv_grid.n_dim
Type: integer Dimensionality of the grid
afv_grid.n_points
Type: integer Total number of nodes This is DEPRECATED, and will be eventually removed. Kept for code-reusability with Mean Field Games Toolbox. Use num_e or num_n instead.
afv_grid.n_weights
Type: (num_n$$\times 1$$) vector of doubles Size of the nodes
afv_grid.num_e
Type: integer Total number of edges
afv_grid.num_n
Type: integer Total number of nodes
afv_grid.num_nb
Type: (num_n$$\times$$n_dim$$\times 2$$) array of integers Number of neighbors of nodes. The third index corresponds to 1: left neighbors 2: right neighbors
afv_grid.x_i
Type: (n_dim$$\times 1$$) cell array of vectors of doubles. Coordinate value of edges or nodes. Users can set this directly.

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. [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 or split, 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
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 the distance to be used in diffusion computation. 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 (n-vector of indices) – indices of the node to compute the mid-point of the edge dir (n-vector of integers) – coordinate direction of the edge to consider is_left_edge (n-vector of bools) – whether computing the mid-points of the left edge or not midpoints of the edge 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 boundaries of the nodes output (matrix of doubles)
afv_grid.compute_num_neighbors(obj)

Compute the number of neighbors

Parameters: n2n – (implicit) n2n [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 the transition matrix of the FPK-equation for the given flows across the edges. A_eFP (num_n$$\times$$num_n sparse matrix of doubles)

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 the transition matrix from the FPK-equation A_FP (num_n$$\times$$num_n sparse matrix of doubles)

Note

afv_grid.compute_transition_matrix_modified(obj, weighter)

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 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 the transition matrix from the FPK-equation A_FP (num_n$$\times$$num_n sparse matrix of doubles)

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 the transition matrix from the FPK-equation A_FP (num_n$$\times$$num_n sparse matrix of doubles)

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 mid-points of the edges

Parameters: ind (vector of indices) – indices of the edges to compute the mid-points mid-points of the edges e_midpoints (vector of doubles)

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 surface area of the edges e_weight (vector of doubles)
afv_grid.extract_edges(obj)

Extract edges from nodal connections. This function only finds internal edges

Parameters: n2n – (implicit) n2n n2bd – (implicit) n2bd [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 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 [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 or split, so one should use that function whenever it is feasible.

afv_grid.node_midpoints(obj, ind)

Compute mid-points of the nodes

Parameters: ind (vector of indices) – (default: ‘:’) indices of the nodes to compute the mid-points n_midpoints (vector of doubles): mid-points 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 volume of the nodes 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 (implicit in class)

Note

Due to object-oriented 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 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 (implicit in class) internally update states to introduce new cells for the given cell