pHtools.h File Reference

Function prototypes, data structures, and defines for pHtools.c. More...

#include <math.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>

Go to the source code of this file.

Classes
struct	BUFFERION
struct	BUFFERLIST
	Buffers which are composed of other buffer solutions use a BUFFERLIST. More...
struct	SPECIES
	Stores concentration information about a charged cation or anion form of an acid or base. More...
struct	BUFFERCOMP
	Stores a single component of a buffer solution. More...
struct	BUFFERSOL
	Stores a buffer solution. More...

Macros
#define	MAX_TRACKED_PHDERIVS   20
#define	MAX_TRACKED_SPECIES   20
#define	CB_ROOT_METHOD   1
#define	MAX_BUFFERIONS   20
#define	MAX_SOLCOMPS   10
#define	MAX_BUFFERCONTAINS   10
#define	MAX_BRENT_ITER   100
#define	MAX_BRENT_EPS   3.0e-8
#define	MAXBUFFSOL   20
#define	LYTES   321

Functions
void	init_buffer_database (void)
	This is how we store a "database" currently. More...
void	create_buffersol (char *name)
	This is the interface method for buffer solution creation. More...
void	deblank (char *s1)
	Removes the leading and trailing blanks from the input string.
int	find_buffersol (char *name)
	Finds a buffer solution among the ones already created and in memory by name.
void	show_all_buffersols (void)
	Displays all buffer solutions currently in memory to the user.
void	setpHtoolsValueSetter (int(*functionPtr)(char *name, double value))
	Sets the function (pointer to function) which is responsible for mapping values to named quantities. More...
void	setpHtoolsValueGetter (int(*functionPtr)(char *name, double *value))
	Sets the function (pointer to function) which is responsible for getting values of named quantities.
void	setpHtoolsValueInitializer (int(*functionPtr)(char *name, double value))
	Sets the function (pointer to function) which is responsible for initializing the value of mapped quantities.
void	setpHtoolsLogFile (FILE *logger)
	Sets the file to which logging is written. More...
void	strupr (char *s)
	Converts string to upper case variant.
int	pHtoolsprintf (char *fmt,...)
	Variation of the standard printf function which prints to a logfile. More...
void	mix_buffersol (char *name, char *ord_pairs)
	Mixes two or more buffer solutions.
void	add_buffersol (char *name, char *ord_pairs)
	Adds new buffer components to a solution according to the name and concentration specified.
double	initialize_pH (char *name)
	Determines and sets the initial pH of the named buffer solution. More...
double	initialize_ionicstr (char *name)
	Determines and sets the initial ionic strength of the named buffer solution.
double	initialize_Cb (char *name)
	Determines and sets the initial Cb of the named buffer solution.
double	initialize_buffcap (char *name)
	Determines and sets the initial buffer capacity of the named buffer solution.
void	track_buffersol (char *name, char *ord_pairs)
	Tracks buffer solution components by name within the named solution.
void	track_species (char *name, char *ord_triplets)
	Tracks anion/cations/uncharged species by name within the named solution.
void	track_ionic_strength (char *name, char *istrnam)
	Tracks the ionic strength by name within the named solution.
void	track_Cb (char *name, char *cbnam)
	Tracks the Cb (a.k.a. More...
void	track_buffcap (char *name, char *bcapnam)
	Tracks the buffer capacity by name within the named solution.
void	track_pH (char *name, char *pHnam, char *dpHdtnam)
int	findspecies (int charge, SPECIES *sp, int nsp)
	Finds the species with the given charge.
BUFFERSOL *	mksol (BUFFERLIST *sollist)
	Ordered pairs of named components and their molar concentrations. More...
void	dilutesol (BUFFERSOL *SOL, double amount)
	Dilutes (or concentrates) all the components within the given solution. More...
void	mixintosol (BUFFERSOL *SOL1, BUFFERSOL *SOL2, double weight)
	Mixes second solution into the first after multiplying its concentration by a weighting factor.
void	addsol (BUFFERSOL *SOL1, BUFFERSOL *SOL2)
	Unions the components of the given solutions. More...
int	struct_cmp_by_nickname (const void *a, const void *b)
	Comparator for qsort of buffer components by their nickname. More...
void	sortandwaterlast (BUFFERSOL *SOL1)
	Sorts a buffer solution's components by their nicknames.
void	listcpy (BUFFERLIST *dest, BUFFERLIST *src)
	Creates a deep copy of a BUFFERLIST.
void	groupcpy (BUFFERION *dest, BUFFERION *src)
	Makes a deep copy of the buffer ion group.
void	speciescpy (SPECIES *dest, SPECIES *src)
	Makes a deep copy of the buffer ion group.
void	compcpy (BUFFERCOMP *dest, BUFFERCOMP *src)
	Makes a deep copy of the given buffer component.
double	initpHCall (BUFFERSOL *SOL, double x1, double x2, double tol)
	Determines the initial pH of a mixture of buffers. More...
double	initpHBisection (BUFFERSOL *SOL, double x1, double x2, double xacc)
	Determine the initial pH of a mixture of buffers. More...
double	initpHBrent (BUFFERSOL *SOL, double x1, double x2, double tol)
	Determines the initial pH of a mixture of buffers. More...
double	Cb (BUFFERSOL *SOL, double pH, int doupdate)
	Evaluates the Cb (a.k.a titration) function for the buffer solution at the given pH.
double	ionicstr (BUFFERSOL *SOL, double pH, int doupdate)
	Evaluates the ionic strength function for the buffer solution at the given pH.
double	buffcapeval (BUFFERSOL *SOL, double pH, int doupdate)
	Evaluates the buffer capacity function for the buffer solution at the given pH.
double	dpHdt (BUFFERSOL *SOL, double pH, BUFFERLIST *derivs)
	Convenience routine which evaluates the time derivative of pH according to. More...
double	dCbdt (BUFFERSOL *SOL, double pH, BUFFERLIST *derivs)
	Evaluate the dCb/dt function for the buffer solution at the given pH. More...
void	showBuffer (BUFFERCOMP *C)
	Pretty-prints the structure and contents of a BUFFERCOMP.
void	showSol (BUFFERSOL *C)
	Pretty-prints the structure and contents of a BUFFERCOMP.
void	species (BUFFERSOL *SOL, double pH, int doupdate)
	Determines the molar concentration of molecular species at the given pH.
double	dCbdH (BUFFERSOL *SOL, double pH)
	Evaluates the dCb/dH function for the buffer solution at the given pH.
BUFFERSOL *	getBufferSolution (int j)
	Gets the jth BUFFERSOL. More...

Variables
BUFFERCOMP *	WATER
BUFFERSOL *	buffersol [MAXBUFFSOL]

Detailed Description

Function prototypes, data structures, and defines for pHtools.c.

Function Documentation

void addsol	(	BUFFERSOL *	SOL1,
		BUFFERSOL *	SOL2
	)

Unions the components of the given solutions.

The concentrations of any shared components are added.

void create_buffersol

(

char *

name

)

This is the interface method for buffer solution creation.

A solution is an aqueous mixture of one or more buffer components. The user only need supply the name they would like to use to refer to this particular solution. Buffer solutions will initially contain only the single buffer component entry for water.

double dCbdt	(	BUFFERSOL *	SOL,
		double	pH,
		BUFFERLIST *	derivs
	)

Evaluate the dCb/dt function for the buffer solution at the given pH.

An ordered list of pairs of named buffer components and time derivatives of their molar concentrations is required. Any unspecified components are assumed to have a molar concentration time derivative equal to zero (unchanged).

void dilutesol	(	BUFFERSOL *	SOL,
		double	amount
	)

Dilutes (or concentrates) all the components within the given solution.

The fractional dilution can be greater than 1 which results in concentration of solution.

double dpHdt	(	BUFFERSOL *	SOL,
		double	pH,
		BUFFERLIST *	derivs
	)

Convenience routine which evaluates the time derivative of pH according to.

dpH/dt =(1/B)*dCbdt

where B is the buffer capacity.

BUFFERSOL* getBufferSolution

(

int

j

)

Gets the jth BUFFERSOL.

Note that the maximum number of buffer solutions is defined by MAXBUFFSOL found in pHtools.h.

void init_buffer_database

(

void

)

This is how we store a "database" currently.

Hopefully can get to something more efficient (tree?) with faster look-up.

double initialize_pH

(

char *

name

)

Determines and sets the initial pH of the named buffer solution.

The initial pH can be used internally to save computation.

double initpHBisection	(	BUFFERSOL *	SOL,
		double	x1,
		double	x2,
		double	xacc
	)

Determine the initial pH of a mixture of buffers.

This algorithm finds the zero (root) of the Cb function and returns the result.

Uses a standard bisection method.

double initpHBrent	(	BUFFERSOL *	SOL,
		double	x1,
		double	x2,
		double	tol
	)

Determines the initial pH of a mixture of buffers.

This algorithm finds the zero (root) of the Cb function and returns the result.

Uses a standard Van Wijngaarden-Dekker-Brent method.

double initpHCall	(	BUFFERSOL *	SOL,
		double	x1,
		double	x2,
		double	tol
	)

Determines the initial pH of a mixture of buffers.

This algorithm finds the zero (root) of the Cb function and returns the result.

Uses a standard Van Wijngaarden-Dekker-Brent method.

BUFFERSOL* mksol

(

BUFFERLIST *

sollist

)

Ordered pairs of named components and their molar concentrations.

The components named here must have a matching component in the bufferDB with the given nickname.

int pHtoolsprintf	(	char *	fmt,
			...
	)

Variation of the standard printf function which prints to a logfile.

Printing is only done if PHTOOLSVERBOSE is defined to be true (==1). If the FILE* logfile is NULL, then printing is done to stdout (just like printf).

void setpHtoolsLogFile

(

FILE *

logger

)

Sets the file to which logging is written.

By default this is stdout. Allows connectivity with client programs wishing to use this library.

void setpHtoolsValueSetter

(

int(*)(char *name, double value)

functionPtr

)

Sets the function (pointer to function) which is responsible for mapping values to named quantities.

Allows connectivity with client programs wishing to use this library.

The typical named quantities, which are updated as soon as they are available, may be set by the user or client program using this library in the following fields of a BUFFERSOL.

• pHnam - Mapped to the current value of pH
• dpHdtnam - Mapped to the current time derivative of pH
• bcapnam - Mapped to the current buffer capacity
• istrnam - Mapped to the current ionic strength
• cbnam - Mapped to the current Cb (a.k.a. titration)

Note: Updating in place can be tuned on or off. The functions buffcapeval, Cb, ionicstr, and species all have prototype (...,int doupdate) where if doupdate==1 the values are mapped as they become available. If doupdate==0 no updating is done of the values.

int struct_cmp_by_nickname	(	const void *	a,
		const void *	b
	)

Comparator for qsort of buffer components by their nickname.

Maintains convention that 'water' is always the last element.

void track_Cb	(	char *	name,
		char *	cbnam
	)

Tracks the Cb (a.k.a.

titration) by name within the named solution.