Documentation for CarbonBoxModel

CarbonBoxModel

Carbon Box Model class which represents the box model which is made up of Box Objects and Flux Objects.

__init__(production_rate_units='kg/yr', flow_rate_units='Gt/yr')

Init method for creating an object of this class.

Parameters:

Name	Type	Description	Default
production_rate_units	str	units for the production rate. Only valid units are 'kg/yr' or 'atoms/cm^2/s'.	'kg/yr'
flow_rate_units	str	units for the flow rate. Only valid values are 'Gt/yr' or '1/yr'.	'Gt/yr'

add_edges(flow_objs)

Adds the flow objects specified in the list to the carbon box model. If any of the objects in the list are not an instance of Flow Class then it throws a ValueError.

Parameters:

Name	Type	Description	Default
flow_objs	list | ndarray	A list of Flow objects to add to the Carbon Box Model.	required

Raises:

Type	Description
ValueError	If any of the objects in the list are not of type Flow.

add_nodes(nodes)

Adds the nodes to the Carbon Box Model. If the node already exists within the carbon box model node list, then it is not added. If the node is not a Box Class Instance, then it raises a ValueError.

Parameters:

Name	Type	Description	Default
nodes	list | ndarray	A list of nodes of Type Box to add to the carbon box model.	required

Raises:

Type	Description
ValueError	If any of the objects in the list are not of type Box.

bin_data(data, time_oversample, time_out, growth)

Bins the data given based on the oversample and the growth season according to Schulman's convention. Can handle any contiguous growth season, even over the year.

Parameters:

Name	Type	Description	Default
data	ndarray	the data which to bin.	required
time_oversample	int	number of samples taken per year.	required
time_out	ndarray	the time values at which to bin the data at.	required
growth	ndarray	the growth season with which to bin the data with respect to.	required

Returns:

Type	Description
DeviceArray	The final binned data accounting for both growth season and Schulman's convention.

Raises:

Type	Description
ValueError	If the data is not one-dimensional or in a single row.

compile()

Method which compiles crucial parts of the model. If the model has not been compiled before then it compiles the following quantities: - 12C reservoir content of the nodes (in the order the nodes were added) - the fluxes (where fluxes at index (i,j) represents the flux from node[i] to node[j]) - the decay matrix (matrix with decay constant along the diagonal) - production coefficients of the nodes. - the corrected fluxes (fluxes in unit 'Gt/yr') - the matrix of the coefficients for the ODEINT to solve. It also detects if the incoming and outgoing fluxes at every node is balanced and if not then throws ValueError along with which node is unbalanced.

Raises:

Type	Description
ValueError	If the incoming flux and outgoing flux at every Box is not balanced.

equilibrate(target_C_14=None, production_rate=None)

External equilibrate method which determines the appropriate result to return given a parameter. If neither parameter is given then it throws a ValueError. If both are specified, then it ignores production_rate.

Parameters:

Name	Type	Description	Default
target_C_14	float	target C14 with which to equilibrate with. Defaults to None.	None
production_rate	float	production rate with which to equilibrate to. Defaults to None.	None

Returns:

Type	Description
float | ndarray	if target C14 is specified, it returns the initial production rate. If the production rate is specified, then it returns a ndarray of the C14 reservoir content.

Raises:

Type	Description
ValueError	If the both arguments are specified as None.

get_converted_fluxes()

Getter method for the fluxes when converted to 'Gt/yr' (this is the unit that the rest of the methods work in internally). This returns None if the compile method has not been run.

Returns:

Type	Description
DeviceArray	2D jax numpy array which contains the unit-corrected fluxes where index (i,j) indicates the 'Gt/yr' flux from node[i] to node[j].

get_edges()

Getter method for the name of edges.

Returns:

Type	Description
list	A list of the edges (given in their string representations i.e. str(source) --> str(destination):flux_value).

get_edges_objects()

Getter method for the edge objects themselves.

Returns:

Type	Description
list	A list of Flow Objects that have been added so far to the Class Object.

get_fluxes()

Getter method for the compiled fluxes in the units specified in the init_method. If the compile method has not been run, then it will return None.

Returns:

Type	Description
DeviceArray	2D jax numpy array which contains the fluxes where index (i,j) indicates the flux from node[i] to node[j].

get_matrix()

Getter method for the ODE coefficient matrix to solve.

Returns:

Type	Description
DeviceArray	jax array of the ODE coefficient matrix to solve.

get_nodes()

Getter method for the name of the nodes in the order they were added to the Carbon Box Model Object.

Returns:

Type	Description
list	A list of node names in the order they were inserted.

get_nodes_objects()

Getter method for the node objects in the order they were inserted.

Returns:

Type	Description
list	A list of the node objects in the order they were inserted.

get_production_coefficients()

Getter method for the normalised production coefficients of the nodes (Boxes). Returns None if compile method has not been called.

Returns:

Type	Description
DeviceArray	jax array containing the normalised production coefficients of the nodes (returned in the order the nodes were added).

get_reservoir_contents()

Getter method for the 12C reservoir content of the nodes (Boxes).. Returns None if the compile method has not been called.

Returns:

Type	Description
DeviceArray	jax numpy array containing the reservoir content of the nodes (returned in the order the nodes were added).

run(time, production, y0=None, args=(), target_C_14=None, steady_state_production=None, solution=None, adaptive=True, step_ts=None)

For the given production function, this calculates the C14 content of all the boxes within the carbon box model at the specified time values. It does this by solving a linear system of ODEs. This method will not work if the compile method has not been executed first.

Parameters:

Name	Type	Description	Default
time	list	the time values at which to calculate the content of all the boxes.	required
production	callable	the production function which determines the contents of the boxes.	required
y0	list	the initial contents of all boxes. Defaults to None. Must be a length(n) list of the same size as the number of boxes.	None
args	tuple	optional arguments to pass into the production function.	()
steady_state_production	int	the steady state production rate with which to equilibrate with to find steady state solution. If y0 is specified, this parameter is ignored.	None
target_C_14	int	target C14 with which to equilibrate with to find steady state solution. If y0 or steady_state_production is specified, this parameter is ignored.	None
solution	ndarray	the equilibrium solution to the ODE system. If this is not specified, then it will be calculated internally. Must be of the same length as the number of boxes.	None

Returns:

Type	Description
Union[list, list]	The value of each box in the carbon box at the specified time_values along with the steady state solution for the system.

Raises:

Type	Description
ValueError	If neither the target C-14 nor production rate is specified. If the production is not a callable function.