Header file for solver functions. More...

Include dependency graph for camp_solver.h:

This graph shows which files directly or indirectly include this file:

Functions
void *	solver_new (int n_state_var, int n_cells, int *var_type, int n_rxn, int n_rxn_int_param, int n_rxn_float_param, int n_rxn_env_param, int n_aero_phase, int n_aero_phase_int_param, int n_aero_phase_float_param, int n_aero_rep, int n_aero_rep_int_param, int n_aero_rep_float_param, int n_aero_rep_env_param, int n_sub_model, int n_sub_model_int_param, int n_sub_model_float_param, int n_sub_model_env_param)
	Get a new solver object.

void	solver_initialize (void solver_data, double abs_tol, double rel_tol, int max_steps, int max_conv_fails)
	Solver initialization.

int	solver_run (void solver_data, double state, double *env, double t_initial, double t_final)
	Solve for a given timestep.

void	solver_get_statistics (void solver_data, int solver_flag, int num_steps, int RHS_evals, int LS_setups, int error_test_fails, int NLS_iters, int NLS_convergence_fails, int DLS_Jac_evals, int DLS_RHS_evals, double last_time_step__s, double next_time_step__s, int Jac_eval_fails, int RHS_evals_total, int Jac_evals_total, double RHS_time__s, double Jac_time__s, double max_loss_precision)
	Get solver statistics after an integration attempt.

void	solver_free (void *solver_data)
	Free a SolverData object.

void	model_free (ModelData model_data)
	Free a ModelData object.

int	f (realtype t, N_Vector y, N_Vector deriv, void *model_data)
	Compute the time derivative f(t,y)

int	Jac (realtype t, N_Vector y, N_Vector deriv, SUNMatrix J, void *model_data, N_Vector tmp1, N_Vector tmp2, N_Vector tmp3)
	Compute the Jacobian.

int	guess_helper (const realtype t_n, const realtype h_n, N_Vector y_n, N_Vector y_n1, N_Vector hf, void *solver_data, N_Vector tmp1, N_Vector corr)

void	error_handler (int error_code, const char module, const char function, char msg, void sd)
	Custom error handling function.

int	camp_solver_update_model_state (N_Vector solver_state, ModelData *model_data, realtype threshhold, realtype replacement_value)
	Update the model state from the current solver state.

SUNMatrix	get_jac_init (SolverData *solver_data)
	Try to improve guesses of y sent to the linear solver.

bool	check_Jac (realtype t, N_Vector y, SUNMatrix J, N_Vector deriv, N_Vector tmp, N_Vector tmp1, void *solver_data)
	Check a Jacobian for accuracy.

int	check_flag (void flag_value, char func_name, int opt)
	Check the return value of a SUNDIALS function.

void	check_flag_fail (void flag_value, char func_name, int opt)
	Check the return value of a SUNDIALS function and exit on failure.

void	solver_reset_timers (void *solver_data)
	Reset the timers for solver functions.

static void	solver_print_stats (void *cvode_mem)

static void	print_data_sizes (ModelData *md)

static void	print_jacobian (SUNMatrix M)

static void	print_derivative (N_Vector deriv)

bool	is_anything_going_on_here (SolverData *sd, realtype t_initial, realtype t_final)
	Determine if there is anything to solve.

Detailed Description

Header file for solver functions.

Definition in file camp_solver.h.

Function Documentation

◆ camp_solver_update_model_state()

int camp_solver_update_model_state	(	N_Vector	solver_state,
		ModelData *	model_data,
		realtype	threshhold,
		realtype	replacement_value
	)

Update the model state from the current solver state.

Parameters

solver_state	Solver state vector
model_data	Pointer to the model data (including the state array)
threshhold	A lower limit for model concentrations below which the solver value is replaced with a replacement value
replacement_value	Replacement value for low concentrations

Returns: CAMP_SOLVER_SUCCESS for successful update or CAMP_SOLVER_FAIL for negative concentration

Definition at line 795 of file camp_solver.c.

Here is the caller graph for this function:

◆ check_flag()

int check_flag	(	void *	flag_value,
		char *	func_name,
		int	opt
	)

Check the return value of a SUNDIALS function.

Parameters

flag_value	A pointer to check (either for NULL, or as an int pointer giving the flag value
func_name	A string giving the function name returning this result code
opt	A flag indicating the type of check to perform (0 for NULL pointer check; 1 for integer flag check)

Returns: Flag indicating CAMP_SOLVER_SUCCESS or CAMP_SOLVER_FAIL

Definition at line 1584 of file camp_solver.c.

Here is the caller graph for this function:

◆ check_flag_fail()

void check_flag_fail	(	void *	flag_value,
		char *	func_name,
		int	opt
	)

Check the return value of a SUNDIALS function and exit on failure.

Parameters

flag_value	A pointer to check (either for NULL, or as an int pointer giving the flag value
func_name	A string giving the function name returning this result code
opt	A flag indicating the type of check to perform (0 for NULL pointer check; 1 for integer flag check)

Definition at line 1614 of file camp_solver.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ check_Jac()

bool check_Jac	(	realtype	t,
		N_Vector	y,
		SUNMatrix	J,
		N_Vector	deriv,
		N_Vector	tmp,
		N_Vector	tmp1,
		void *	solver_data
	)

Check a Jacobian for accuracy.

This function compares Jacobian elements against differences in derivative calculations for small changes to the state array:

\[ J_{ij}(x) = \frac{f_i(x+\sum_j e_j) - f_i(x)}{\epsilon} \]

where \(\epsilon_j = 10^{-8} \left|x_j\right|\)

Parameters

t	Current time [s]
y	Current state array
J	Jacobian matrix to evaluate
deriv	Current derivative \(f(y)\)
tmp	Working array the size of \(y\)
tmp1	Working array the size of \(y\)
solver_data	Solver data

Returns: True if Jacobian values are accurate, false otherwise

Definition at line 1136 of file camp_solver.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ error_handler()

void error_handler	(	int	error_code,
		const char *	module,
		const char *	function,
		char *	msg,
		void *	sd
	)

Custom error handling function.

This is used for quiet operation. Solver failures are returned with a flag from the solver_run() function.

Definition at line 1767 of file camp_solver.c.

Here is the caller graph for this function:

◆ f()

int f	(	realtype	t,
		N_Vector	y,
		N_Vector	deriv,
		void *	solver_data
	)

Compute the time derivative f(t,y)

Parameters

t	Current model time (s)
y	Dependent variable array
deriv	Time derivative vector f(t,y) to calculate
solver_data	Pointer to the solver data

Returns: Status code

Definition at line 833 of file camp_solver.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_jac_init()

SUNMatrix get_jac_init ( SolverData * solver_data )

Try to improve guesses of y sent to the linear solver.

This function checks if there are any negative guessed concentrations, and if there are it calculates a set of initial corrections to the guessed state using the state at time \(t_{n-1}\) and the derivative \(f_{n-1}\) and advancing the state according to:

\[ y_n = y_{n-1} + \sum_{j=1}^m h_j * f_j \]

where \(h_j\) is the largest timestep possible where

\[ y_{j-1} + h_j * f_j > 0 \]

and

\[ t_n = t_{n-1} + \sum_{j=1}^m h_j \]

Parameters

t_n	Current time [s]
h_n	Current time step size [s] If this is set to zero, the change hf is assumed to be an adjustment where y_n = y_n1 + hf
y_n	Current guess for \(y(t_n)\)
y_n1	\(y(t_{n-1})\)
hf	Current guess for change in \(y\) from \(t_{n-1}\) to \(t_n\) [input/output]
solver_data	Solver data
tmp1	Temporary vector for calculations
corr	Vector of calculated adjustments to \(y(t_n)\) [output]

Returns: 1 if corrections were calculated, 0 if not

Create a sparse Jacobian matrix based on model data

Parameters

solver_data A pointer to the SolverData

Returns: Sparse Jacobian matrix with all possible non-zero elements intialize to 1.0

Todo:: Make the Jacobian mapping recursive for sub model parameters that depend on other sub model parameters

Definition at line 1278 of file camp_solver.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ guess_helper()

int guess_helper	(	const realtype	t_n,
		const realtype	h_n,
		N_Vector	y_n,
		N_Vector	y_n1,
		N_Vector	hf,
		void *	solver_data,
		N_Vector	tmp1,
		N_Vector	corr
	)

Here is the caller graph for this function:

◆ is_anything_going_on_here()

bool is_anything_going_on_here	(	SolverData *	sd,
		realtype	t_initial,
		realtype	t_final
	)

Determine if there is anything to solve.

If the solver state concentrations and the derivative vector are very small, there is no point running the solver

Definition at line 1736 of file camp_solver.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Jac()

int Jac	(	realtype	t,
		N_Vector	y,
		N_Vector	deriv,
		SUNMatrix	J,
		void *	solver_data,
		N_Vector	tmp1,
		N_Vector	tmp2,
		N_Vector	tmp3
	)

Compute the Jacobian.

Parameters

t	Current model time (s)
y	Dependent variable array
deriv	Time derivative vector f(t,y)
J	Jacobian to calculate
solver_data	Pointer to the solver data
tmp1	Unused vector
tmp2	Unused vector
tmp3	Unused vector

Returns: Status code

Todo:: #83 Figure out how to stop CVODE from resizing the Jacobian during solving

Definition at line 962 of file camp_solver.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ model_free()

void model_free ( ModelData model_data )

Free a ModelData object.

Parameters

model_data Pointer to the ModelData object to free

Definition at line 1776 of file camp_solver.c.

Here is the caller graph for this function:

◆ print_data_sizes()

static void print_data_sizes ( ModelData * md )

static

◆ print_derivative()

static void print_derivative ( N_Vector deriv )

static

◆ print_jacobian()

static void print_jacobian ( SUNMatrix M )

static

◆ solver_free()

void solver_free ( void * solver_data )

Free a SolverData object.

Parameters

solver_data Pointer to the SolverData object to free

Definition at line 1693 of file camp_solver.c.

Here is the call graph for this function:

◆ solver_get_statistics()

void solver_get_statistics	(	void *	solver_data,
		int *	solver_flag,
		int *	num_steps,
		int *	RHS_evals,
		int *	LS_setups,
		int *	error_test_fails,
		int *	NLS_iters,
		int *	NLS_convergence_fails,
		int *	DLS_Jac_evals,
		int *	DLS_RHS_evals,
		double *	last_time_step__s,
		double *	next_time_step__s,
		int *	Jac_eval_fails,
		int *	RHS_evals_total,
		int *	Jac_evals_total,
		double *	RHS_time__s,
		double *	Jac_time__s,
		double *	max_loss_precision
	)

Get solver statistics after an integration attempt.

Parameters

solver_data	Pointer to the solver data
solver_flag	Last flag returned by the solver
num_steps	Pointer to set to the number of integration steps
RHS_evals	Pointer to set to the number of right-hand side evaluations
LS_setups	Pointer to set to the number of linear solver setups
error_test_fails	Pointer to set to the number of error test failures
NLS_iters	Pointer to set to the non-linear solver iterations
NLS_convergence_fails	Pointer to set to the non-linear solver convergence failures
DLS_Jac_evals	Pointer to set to the direct linear solver Jacobian evaluations
DLS_RHS_evals	Pointer to set to the direct linear solver right-hand side evaluations
last_time_step__s	Pointer to set to the last time step size [s]
next_time_step__s	Pointer to set to the next time step size [s]
Jac_eval_fails	Number of Jacobian evaluation failures
RHS_evals_total	Total calls to `f()`
Jac_evals_total	Total calls to `Jac()`
RHS_time__s	Compute time for calls to f() [s]
Jac_time__s	Compute time for calls to Jac() [s]
max_loss_precision	Indicators of loss of precision in derivative calculation for each species

Definition at line 715 of file camp_solver.c.

Here is the call graph for this function:

◆ solver_initialize()

void solver_initialize	(	void *	solver_data,
		double *	abs_tol,
		double	rel_tol,
		int	max_steps,
		int	max_conv_fails
	)

Solver initialization.

Allocate and initialize solver objects

Parameters

solver_data	Pointer to a SolverData object
abs_tol	Pointer to array of absolute tolerances
rel_tol	Relative integration tolerance
max_steps	Maximum number of internal integration steps
max_conv_fails	Maximum number of convergence failures

Definition at line 364 of file camp_solver.c.

Here is the call graph for this function:

◆ solver_new()

void * solver_new	(	int	n_state_var,
		int	n_cells,
		int *	var_type,
		int	n_rxn,
		int	n_rxn_int_param,
		int	n_rxn_float_param,
		int	n_rxn_env_param,
		int	n_aero_phase,
		int	n_aero_phase_int_param,
		int	n_aero_phase_float_param,
		int	n_aero_rep,
		int	n_aero_rep_int_param,
		int	n_aero_rep_float_param,
		int	n_aero_rep_env_param,
		int	n_sub_model,
		int	n_sub_model_int_param,
		int	n_sub_model_float_param,
		int	n_sub_model_env_param
	)

Get a new solver object.

Return a pointer to a new SolverData object

Parameters

n_state_var	Number of variables on the state array per grid cell
n_cells	Number of grid cells to solve simultaneously
var_type	Pointer to array of state variable types (solver, constant, PSSA)
n_rxn	Number of reactions to include
n_rxn_int_param	Total number of integer reaction parameters
n_rxn_float_param	Total number of floating-point reaction parameters
n_rxn_env_param	Total number of environment-dependent reaction parameters
n_aero_phase	Number of aerosol phases
n_aero_phase_int_param	Total number of integer aerosol phase parameters
n_aero_phase_float_param	Total number of floating-point aerosol phase parameters
n_aero_rep	Number of aerosol representations
n_aero_rep_int_param	Total number of integer aerosol representation parameters
n_aero_rep_float_param	Total number of floating-point aerosol representation parameters
n_aero_rep_env_param	Total number of environment-dependent aerosol representation parameters
n_sub_model	Number of sub models
n_sub_model_int_param	Total number of integer sub model parameters
n_sub_model_float_param	Total number of floating-point sub model parameters
n_sub_model_env_param	Total number of environment-dependent sub model parameters

Returns: Pointer to the new SolverData object

Definition at line 73 of file camp_solver.c.

Here is the call graph for this function:

◆ solver_print_stats()

static void solver_print_stats ( void * cvode_mem )

static

◆ solver_reset_timers()

void solver_reset_timers ( void * solver_data )

Reset the timers for solver functions.

Parameters

solver_data Pointer to the SolverData object with timers to reset

Definition at line 1625 of file camp_solver.c.

◆ solver_run()

int solver_run	(	void *	solver_data,
		double *	state,
		double *	env,
		double	t_initial,
		double	t_final
	)

Solve for a given timestep.

Parameters

solver_data	A pointer to the initialized solver data
state	A pointer to the full state array (all grid cells)
env	A pointer to the full array of environmental conditions (all grid cells)
t_initial	Initial time (s)
t_final	(s)

Returns: Flag indicating CAMP_SOLVER_SUCCESS or CAMP_SOLVER_FAIL

Definition at line 534 of file camp_solver.c.

Here is the call graph for this function:

Functions

Detailed Description

Function Documentation

◆ camp_solver_update_model_state()

◆ check_flag()

◆ check_flag_fail()

◆ check_Jac()

◆ error_handler()

◆ f()

◆ get_jac_init()

◆ guess_helper()

◆ is_anything_going_on_here()

◆ Jac()

◆ model_free()

◆ print_data_sizes()

◆ print_derivative()

◆ print_jacobian()

◆ solver_free()

◆ solver_get_statistics()

◆ solver_initialize()

◆ solver_new()

◆ solver_print_stats()

◆ solver_reset_timers()

◆ solver_run()