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
Description:	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
Description:	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
Description:	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 integers
Description:	Normal/coordinate direction of the edge

afv_grid.e2n¶

Type:	(`num_e` \(\times\) 2)-matrix of integers
Description:	Connectivity graph from edges to nodes

afv_grid.e_weights¶

Type:	(`num_e`\(\times 1\))-vector of doubles
Description:	(integral) weights of the edges

afv_grid.n2bd¶

Type:	(`afv_grid.num_e` \(\times\) (2 \(\cdot\) `afv_grid.n_dim` ) )-matrix of doubles
Description:	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 integers
Description:	Connectivity graph from nodes to edges.

afv_grid.n2n¶

Type:

(num_n\(\times\)n_dim\(\times 2\)) cell of integers

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 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
Description:	Size of the nodes

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:

(num_n\(\times\)n_dim\(\times 2\)) array of integers

Description:

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.
Description:	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.

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 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

See also

set_dim

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 (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
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 FPK-equation for the given flows across the edges.
Return type:	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
Returns:	the transition matrix from the FPK-equation
Return type:	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.
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 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
Returns:	the transition matrix from the FPK-equation
Return type:	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

[Axelsson & Gustafsson, 1979]

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 FPK-equation
Return type:	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
Returns:	mid-points of the edges
Return type:	e_midpoints (vector of doubles)

See also

compute_edge_midpoints

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:

n2n – (implicit) n2n
n2bd – (implicit) n2bd

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 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
Returns:	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
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 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
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