BMIPhreeqcRM Module Reference

Data Types
type	bmi

Functions/Subroutines
integer function	bmif_create_default (self)
integer function	bmif_create (self, nxyz, nthreads)
integer function	bmif_initialize (self, config_file)
integer function	bmif_get_id (self)
integer function	bmif_update (self)
integer function	bmif_update_until (self, end_time)
integer function	bmif_finalize (self)
integer function	bmif_get_component_name (self, component_name)
integer function	bmif_get_input_item_count (self, count)
integer function	bmif_get_output_item_count (self, count)
integer function	bmif_get_pointable_item_count (self, count)
integer function	bmif_get_input_var_names (self, var_names)
integer function	bmif_get_output_var_names (self, var_names)
integer function	bmif_get_pointable_var_names (self, var_names)
integer function	bmif_get_var_grid (self, var, grid)
integer function	bmif_get_var_type (self, var, vtype)
integer function	bmif_get_var_units (self, var, units)
integer function	bmif_get_var_itemsize (self, var, itemsize)
integer function	bmif_get_var_nbytes (self, var, nbytes)
integer function	bmif_get_current_time (self, time)
integer function	bmif_get_start_time (self, start_time)
integer function	bmif_get_time (self, start_time)
integer function	bmif_get_end_time (self, end_time)
integer function	bmif_get_time_units (self, time_units)
integer function	bmif_get_time_step (self, time_step)
integer function	bmif_get_value_logical (self, var, dest)
integer function	bmif_get_value_char (self, var, dest)
integer function	bmif_get_value_char_alloc (self, var, dest)
integer function	bmif_get_value_char1 (self, var, dest)
integer function	bmif_get_value_double (self, var, dest)
integer function	bmif_get_value_double1 (self, var, dest)
integer function	bmif_get_value_double2 (self, var, dest)
integer function	bmif_get_value_int (self, var, dest)
integer function	bmif_get_value_int1 (self, var, dest)
integer function	bmif_get_value_int2 (self, var, dest)
integer function	bmif_get_value_ptr_double (self, var, ptr)
integer function	bmif_get_value_ptr_double1 (self, var, ptr)
integer function	bmif_get_value_ptr_integer (self, var, ptr)
integer function	bmif_get_value_ptr_logical (self, var, ptr)
integer function	bmif_set_value_b (self, var, src)
integer function	bmif_set_value_c (self, var, src)
integer function	bmif_set_value_int (self, var, src)
integer function	bmif_set_value_int1 (self, var, src)
integer function	bmif_set_value_int2 (self, var, src)
integer function	bmif_set_value_double (self, var, src)
integer function	bmif_set_value_double1 (self, var, src)
integer function	bmif_set_value_double2 (self, var, src)
integer function	bmif_grid_rank (self, grid, rank)
integer function	bmif_grid_size (self, grid, ngrid)
integer function	bmif_grid_type (self, grid, str)
integer function	bmif_add_output_vars (self, option, def)
integer function	Abort (self, iresult, err_str)
integer function	CloseFiles (self)
integer function	Concentrations2Utility (self, c, n, tc, p_atm)
integer function	CreateMapping (self, grid2chem)
integer function	DecodeError (self, e)
integer function	Destroy (self)
integer function	DumpModule (self, dump_on, append)
integer function	ErrorMessage (self, errstr)
integer function	FindComponents (self)
integer function	GetBackwardMapping (self, n, list)
integer function	GetChemistryCellCount (self)
integer function	GetComponents (self, components)
integer function	GetComponentCount (self)
integer function	GetConcentrations (self, c)
integer function	GetCurrentSelectedOutputUserNumber (self)
integer function	GetDensityCalculated (self, density)
integer function	GetDensity (self, density)
integer function	GetEndCell (self, ec)
integer function	GetEquilibriumPhasesCount (self)
integer function	GetEquilibriumPhasesNames (self, names)
integer function	GetErrorString (self, errstr)
integer function	GetExchangeNames (self, names)
integer function	GetExchangeSpeciesCount (self)
integer function	GetExchangeSpeciesNames (self, names)
integer function	GetFilePrefix (self, prefix)
integer function	GetGasComponentsCount (self)
integer function	GetGasComponentsNames (self, names)
integer function	GetGasCompMoles (self, gas_moles)
integer function	GetGasCompPressures (self, gas_p)
integer function	GetGasCompPhi (self, gas_phi)
integer function	GetGasPhaseVolume (self, gas_volume)
integer function	GetGfw (self, gfw)
integer function	GetGridCellCount (self)
integer function	GetIPhreeqcId (self, i)
integer function	GetIthConcentration (self, i, c)
integer function	GetIthSpeciesConcentration (self, i, c)
integer function	GetKineticReactionsCount (self)
integer function	GetKineticReactionsNames (self, names)
integer function	GetMpiMyself (self)
integer function	GetMpiTasks (self)
integer function	GetNthSelectedOutputUserNumber (self, n)
integer function	GetPorosity (self, porosity)
integer function	GetPressure (self, pressure)
integer function	GetSaturationCalculated (self, sat_calc)
integer function	GetSaturation (self, sat_calc)
integer function	GetSelectedOutput (self, so)
integer function	GetSelectedOutputColumnCount (self)
integer function	GetSelectedOutputCount (self)
integer function	GetSelectedOutputHeadings (self, headings)
integer function	GetSelectedOutputRowCount (self)
integer function	GetSICount (self)
integer function	GetSINames (self, names)
integer function	GetSolidSolutionComponentsCount (self)
integer function	GetSolidSolutionComponentsNames (self, names)
integer function	GetSolidSolutionNames (self, names)
integer function	GetSolutionVolume (self, vol)
integer function	GetSpeciesConcentrations (self, species_conc)
integer function	GetSpeciesCount (self)
integer function	GetSpeciesD25 (self, diffc)
integer function	GetSpeciesLog10Gammas (self, species_log10gammas)
integer function	GetSpeciesLog10Molalities (self, species_log10molalities)
integer function	GetSpeciesNames (self, names)
integer function	GetSpeciesSaveOn (self)
integer function	GetSpeciesZ (self, z)
integer function	GetStartCell (self, sc)
integer function	GetSurfaceNames (self, names)
integer function	GetSurfaceSpeciesCount (self)
integer function	GetSurfaceSpeciesNames (self, names)
integer function	GetSurfaceTypes (self, names)
integer function	GetTemperature (self, temperature)
integer function	GetThreadCount (self)
real(kind=8) function	GetTime (self)
real(kind=8) function	GetTimeconversion (self)
real(kind=8) function	GetTimestep (self)
integer function	GetViscosity (self, viscosity)
integer function	InitializeYAML (self, yaml_name)
integer function	InitialPhreeqc2Concentrations (self, bc_conc, n_boundary, bc1, bc2, f1)
integer function	InitialPhreeqc2Module (self, ic1, ic2, f1)
integer function	InitialSolutions2Module (self, solutions)
integer function	InitialEquilibriumPhases2Module (self, equilibrium_phases)
integer function	InitialExchanges2Module (self, exchanges)
integer function	InitialGasPhases2Module (self, gas_phases)
integer function	InitialSolidSolutions2Module (self, solid_solutions)
integer function	InitialSurfaces2Module (self, surfaces)
integer function	InitialKinetics2Module (self, kinetics)
integer function	InitialPhreeqc2SpeciesConcentrations (self, bc_conc, n_boundary, bc1, bc2, f1)
integer function	InitialPhreeqcCell2Module (self, n_user, cell_numbers, n_cell)
integer function	LoadDatabase (self, db_name)
integer function	LogMessage (self, str)
integer function	MpiWorker (self)
integer function	MpiWorkerBreak (self)
integer function	OpenFiles (self)
integer function	OutputMessage (self, str)
integer function	RunCells (self)
integer function	RunFile (self, workers, initial_phreeqc, utility, chem_name)
integer function	RunString (self, workers, initial_phreeqc, utility, input_string)
integer function	ScreenMessage (self, str)
integer function	SetComponentH2O (self, tf)
integer function	SetConcentrations (self, c)
integer function	SetCurrentSelectedOutputUserNumber (self, n_user)
integer function	SetDensityUser (self, density)
integer function	SetDensity (self, density)
integer function	SetDumpFileName (self, dump_name)
integer function	SetErrorHandlerMode (self, mode)
integer function	SetErrorOn (self, tf)
integer function	SetFilePrefix (self, prefix)
integer function	SetGasCompMoles (self, gas_moles)
integer function	SetGasPhaseVolume (self, gas_volume)
integer function	SetIthConcentration (self, i, c)
integer function	SetIthSpeciesConcentration (self, i, c)
integer function	SetMpiWorkerCallback (self, fcn)
integer function	SetNthSelectedOutput (self, n)
integer function	SetPartitionUZSolids (self, tf)
integer function	SetPorosity (self, por)
integer function	SetPressure (self, p)
integer function	SetPrintChemistryMask (self, cell_mask)
integer function	SetPrintChemistryOn (self, workers, initial_phreeqc, utility)
integer function	SetRebalanceByCell (self, method)
integer function	SetRebalanceFraction (self, f)
integer function	SetRepresentativeVolume (self, rv)
integer function	SetSaturationUser (self, sat)
integer function	SetSaturation (self, sat)
integer function	SetScreenOn (self, tf)
integer function	SetSelectedOutputOn (self, tf)
integer function	SetSpeciesSaveOn (self, save_on)
integer function	SetTemperature (self, t)
integer function	SetTime (self, time)
integer function	SetTimeConversion (self, conv_factor)
integer function	SetTimeStep (self, time_step)
integer function	SetUnitsExchange (self, option)
integer function	SetUnitsGasPhase (self, option)
integer function	SetUnitsKinetics (self, option)
integer function	SetUnitsPPassemblage (self, option)
integer function	SetUnitsSolution (self, option)
integer function	SetUnitsSSassemblage (self, option)
integer function	SetUnitsSurface (self, option)
integer function	SpeciesConcentrations2Module (self, species_conc)
integer function	StateSave (self, istate)
integer function	StateApply (self, istate)
integer function	StateDelete (self, istate)
integer function	UseSolutionDensityVolume (self, tf)
integer function	WarningMessage (self, warn_str)

Variables
integer, parameter	bmi_max_component_name = 2048
integer, parameter	bmi_max_var_name = 2048
integer, parameter	bmi_max_type_name = 2048
integer, parameter	bmi_max_units_name = 2048
integer, parameter	bmi_failure = 1
integer, parameter	bmi_success = 0

Detailed Description

Fortran documentation for the geochemical reaction module BMIPhreeqcRM.

"USE BMIPhreeqcRM" defines a module with both Basic Model Interface methods and native PhreeqcRM methods for Fortran programs.
For Windows, include the files BMI_interface.F90 and RM_interface.F90 in your project.
For Linux, configure, compile, and install the PhreeqcRM library and module file. You will need installed include directory (-I) added to the project to reference the module file. You will need to link to the library to produce the executable for your code.

Function/Subroutine Documentation

Abort()

integer function BMIPhreeqcRM::Abort	(	class(bmi), intent(inout)	self,
		integer, intent(in)	iresult,
		character(len=*), intent(in)	err_str
	)

Abort the program. iresult will be interpreted as an IRESULT value and decoded; err_str will be printed; and the reaction module will be Destroyed. If using MPI, an MPI_Abort message will be sent before the reaction module is Destroyed. If the id is an invalid instance, Abort will return a value ofIBADINSTANCE, otherwise the program will exit with a return code of 4.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
iresult	Integer treated as an IRESULT return code.
err_str	String to be printed as an error message.

Return values

IRESULT

Program will exit before returning unless id is an invalid reaction module id.

See also

Destroy, ErrorMessage.

Fortran Example:

 string = "SELECTED_OUTPUT 5; -pH;RUN_CELLS; -cells 1"
 status = brm%RunString(string)
 if (status .lt. 0) status = brm%Abort(status, "RunString failed")
 

MPI:

Called by root or workers.

bmif_add_output_vars()

integer function BMIPhreeqcRM::bmif_add_output_vars	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	option,
		character(len=*), intent(in)	def
	)

bmif_add_output_vars allows selection of sets of variables that can be retieved by the bmi::bmif_get_value method. Sets of variables can be included or excluded with multiple calls to this method. All calls must precede the final call to the PhreeqcRM method FindComponents. FindComponents generates SELECTED_OUTPUT 333 and USER_PUNCH 333 data blocks that make the variables accessible. Variables will only be accessible if the system includes the given reactant; for example, no gas variables will be Created if there are no GAS_PHASEs in the model.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
option	A string value, among those listed below, that includes or excludes variables from bmif_get_output_var_names, bmi::bmif_get_value, and other BMI methods.
def	A string value that can be "false", "true", or a list of items to be included as accessible variables. A value of "false", excludes all variables of the given type; a value of "true" includes all variables of the given type for the current system; a list specifies a subset of items of the given type.

Values for the the parameter option:
AddOutputVars: False excludes all variables; True causes the settings for each variable group to determine the variables that will be defined. Default True;
SolutionProperties: False excludes all solution property variables; True includes variables pH, pe, alkalinity, ionic strength, water mass, charge balance, percent error, and specific conductance. Default True.
SolutionTotalMolalities: False excludes all total element and element redox state variables; True includes all elements and element redox state variables for the system defined for the calculation; list restricts variables to the specified elements and redox states. Default True.
ExchangeMolalities: False excludes all variables related to exchange; True includes all variables related to exchange; list includes variables for the specified exchange species. Default True.
SurfaceMolalities: False excludes all variables related to surfaces; True includes all variables related to surfaces; list includes variables for the specified surface species. Default True.
EquilibriumPhases: False excludes all variables related to equilibrium phases; True includes all variables related to equilibrium phases; list includes variables for the specified equilibiurm phases. Default True.
Gases: False excludes all variables related to gases; True includes all variables related to gases; list includes variables for the specified gas components. Default True.
KineticReactants: False excludes all variables related to kinetic reactants; True includes all variables related to kinetic reactants; list includes variables for the specified kinetic reactants. Default True.
SolidSolutions: False excludes all variables related to solid solutions; True includes all variables related to solid solutions; list includes variables for the specified solid solutions components. Default True.
CalculateValues: False excludes all calculate values; True includes all calculate values; list includes the specified calculate values. CALCLUATE_VALUES can be used to calculate geochemical quantities not available in the other sets of variables. Default True.
SolutionActivities: False excludes all aqueous species; True includes all aqueous species; list includes only the specified aqueous species. Default False.
SolutionMolalities: False excludes all aqueous species; True includes all aqueous species; list includes only the specified aqueous species. Default False.
SaturationIndices: False excludes all saturation indices; True includes all saturation indices; list includes only the specified saturation indices. Default False.

Fortran Example:

 status = brm%bmif_add_output_vars("SolutionMolalities", "True")
 status = brm%bmif_add_output_vars("SaturationIndices", "Calcite Dolomite")
 

bmif_create()

integer function BMIPhreeqcRM::bmif_create	(	class(bmi), intent(inout)	self,
		integer, intent(in)	nxyz,
		integer, intent(in)	nthreads
	)

bmif_create Creates a reaction module. The reaction module must be initialized with a call to bmif_initialize. If the code is compiled with the preprocessor directive USE_OPENMP, the reaction module is multithreaded. If the code is compiled with the preprocessor directive USE_MPI, the reaction module will use MPI and multiple processes. If neither preprocessor directive is used, the reaction module will be serial (unparallelized).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
nxyz	The number of grid cells in the user's model.
nthreads	(or comm, MPI) When using OPENMP, the argument (nthreads) is the number of worker threads to be used. If nthreads <= 0, the number of threads is set equal to the number of processors of the computer. When using MPI, the argument (comm) is the MPI communicator to use within the reaction module.

Return values

Id	of the BMIPhreeqcRM instance, negative is failure.

See also

bmif_finalize.

Fortran example:

 nxyz = 40
 nthreads = 3
 id = brm%bmif_create(nxyz, nthreads)
 

MPI:

Called by root and workers.

bmif_create_default()

integer function BMIPhreeqcRM::bmif_create_default

(

class(bmi), intent(inout)

self

)

bmif_create Creates a BMIPhreeqcRM instance. The default method, with no arguments, can be used if the instance is to be initialized with a YAML file. The YAML file must provide the number of cells in the user's model through the YAMLSetGridCellCount method, and, optionally, the number of threads with YAMLThreadCount. The default method cannot be used with MPI.

bmif_finalize()

integer function BMIPhreeqcRM::bmif_finalize

(

class(bmi), intent(inout)

self

)

bmif_finalize Destroys a reaction module, same as Destroy.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

0	is success, 1 is failure.

See also

bmif_create.

Fortran example:

 status = brm%bmif_finalize()
 

MPI:

Called by root and workers.

bmif_get_component_name()

integer function BMIPhreeqcRM::bmif_get_component_name	(	class(bmi), intent(inout)	self,
		character(len=*), intent(inout)	component_name
	)

bmif_get_component_name returns the component name–BMIPhreeqcRM.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
component_name	Filled with "BMIPhreeqcRM", the name of the component.

Return values

0	is success, 1 is failure.

Fortran example:

 status = brm%bmif_get_component_name(component_name)
 

MPI:

Called by root.

bmif_get_current_time()

integer function BMIPhreeqcRM::bmif_get_current_time	(	class(bmi), intent(inout)	self,
		real(kind=8), intent(inout)	time
	)

bmif_get_current_time returns the current simulation time, in seconds. (Same as GetTime.)

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
time	The current simulation time, in seconds.

Return values

0	is success, 1 is failure.

See also

bmif_get_end_time, bmif_get_time_step, bmi::bmif_set_value, GetTime, GetTimestep, SetTime, SetTimeStep.

Fortran example:

 status = brm%bmif_get_current_time(time)
 

MPI:

Called by root.

bmif_get_end_time()

integer function BMIPhreeqcRM::bmif_get_end_time	(	class(bmi), intent(inout)	self,
		real(kind=8), intent(inout)	end_time
	)

bmif_get_end_time returns bmif_get_current_time plus bmif_get_time_step, in seconds.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
end_time	The end of the time step, in seconds.

Return values

0	is success, 1 is failure.

See also

bmif_get_current_time, bmif_get_time_step, bmi::bmif_set_value, GetTime, GetTimestep, SetTime, SetTimeStep.

Fortran example:

 status = brm%bmif_get_end_time(end_time)
 

MPI:

Called by root.

bmif_get_id()

integer function BMIPhreeqcRM::bmif_get_id

(

class(bmi), intent(inout)

self

)

bmif_get_input_item_count()

integer function BMIPhreeqcRM::bmif_get_input_item_count	(	class(bmi), intent(inout)	self,
		integer, intent(inout)	count
	)

bmif_get_input_item_count returns count of variables that can be set with bmi::bmif_set_value.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
count	Number of input variables that can be set with bmi::bmif_set_value.

Return values

0	is success, 1 is failure.

See also

bmif_get_input_var_names, bmif_get_var_itemsize, bmif_get_var_nbytes, bmif_get_var_type, bmif_get_var_units, bmi::bmif_set_value.

Fortran example:

 status = brm%bmif_get_input_item_count(count)
 

MPI:

Called by root.

bmif_get_input_var_names()

integer function BMIPhreeqcRM::bmif_get_input_var_names	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	var_names
	)

Basic Model Interface method that returns a list of the variable names that can be set with bmi::bmif_set_value.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
var_names	Character array of variable names.

Return values

0	is success, 1 is failure.

See also

bmif_get_input_item_count, bmi::bmif_get_value, bmif_get_var_itemsize, bmif_get_var_nbytes, bmif_get_var_type, bmif_get_var_units, bmi::bmif_set_value.

Fortran example:

 character(len=:), dimension(:), allocatable :: inputvars
 status = brm%bmif_get_input_var_names(inputvars)
 

MPI:

Called by root.

bmif_get_output_item_count()

integer function BMIPhreeqcRM::bmif_get_output_item_count	(	class(bmi), intent(inout)	self,
		integer, intent(inout)	count
	)

bmif_get_output_item_count returns count of output variables that can be retrieved with bmi::bmif_get_value.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
count	Number of output variables that can be retrieved with bmi::bmif_get_value.

Return values

0	is success, 1 is failure.

See also

bmif_get_output_var_names, bmi::bmif_get_value, bmif_get_var_itemsize, bmif_get_var_nbytes, bmif_get_var_type, bmif_get_var_units.

Fortran example:

 status = brm%bmif_get_output_item_count(outputvarcount)
 

MPI:

Called by root.

bmif_get_output_var_names()

integer function BMIPhreeqcRM::bmif_get_output_var_names	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	var_names
	)

bmif_get_output_var_names returns a list of the variable names that can be retrieved with bmi::bmif_get_value.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
var_names	Character array of variable names.

Return values

0	is success, 1 is failure.

See also

bmif_get_output_item_count, bmi::bmif_get_value, bmif_get_var_itemsize, bmif_get_var_nbytes, bmif_get_var_type, bmif_get_var_units.

Fortran example:

 character(len=:), allocatable, dimension(:) :: var_names
 status = brm%bmif_get_output_var_names(var_names)
 

MPI:

Called by root.

bmif_get_pointable_item_count()

integer function BMIPhreeqcRM::bmif_get_pointable_item_count	(	class(bmi), intent(inout)	self,
		integer, intent(inout)	count
	)

bmif_get_pointable_item_count returns count of variables for which pointers can be retrieved with bmi::bmif_get_value_ptr.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
count	Number of variables for which pointers can be retrieved with bmi::bmif_get_value_ptr.

Return values

0	is success, 1 is failure.

See also

bmif_get_input_var_names, bmif_get_var_itemsize, bmif_get_var_nbytes, bmif_get_var_type, bmif_get_var_units, bmi::bmif_set_value.

Fortran example:

 status = brm%bmif_get_pointable_item_count(pointablevarcount)
 

MPI:

Called by root.

bmif_get_pointable_var_names()

integer function BMIPhreeqcRM::bmif_get_pointable_var_names	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	var_names
	)

bmif_get_pointable_var_names returns a list of the variable names for which a pointer can be retrieved with bmi::bmif_get_value_ptr.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
var_names	Character array of variable names.

Return values

0	is success, 1 is failure.

See also

bmif_get_pointable_item_count, bmi::bmif_get_value, bmif_get_var_itemsize, bmif_get_var_nbytes, bmif_get_var_type, bmif_get_var_units.

Fortran example:

 character(len=:), allocatable, dimension(:) :: var_names
 status = brm%bmif_get_pointable_var_names(var_names)
 

MPI:

Called by root.

bmif_get_start_time()

integer function BMIPhreeqcRM::bmif_get_start_time	(	class(bmi), intent(inout)	self,
		real(kind=8), intent(inout)	start_time
	)

bmif_get_start_time returns the current simulation time, in seconds. (Same as bmif_get_current_time and GetTime.)

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
start_time	The current simulation time, in seconds.

Return values

0	is success, 1 is failure.

bmif_get_time()

integer function BMIPhreeqcRM::bmif_get_time	(	class(bmi), intent(inout)	self,
		real(kind=8), intent(inout)	start_time
	)

bmif_get_time returns the current simulation time, in seconds. (Same as bmif_get_current_time and GetTime.)

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
start_time	The current simulation time, in seconds.

Return values

0	is success, 1 is failure.

bmif_get_time_step()

integer function BMIPhreeqcRM::bmif_get_time_step	(	class(bmi), intent(inout)	self,
		real(kind=8), intent(inout)	time_step
	)

bmif_get_time_step returns the current simulation time step, in seconds. (Same as GetTimestep.)

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
time_step	The current simulation time step, in seconds.

Return values

0	is success, 1 is failure.

See also

bmif_get_current_time, bmif_get_end_time, bmi::bmif_set_value, GetTime, GetTimestep, SetTime, SetTimeStep.

Fortran example:

 status = brm%bmif_get_time_step(time_step)
 

MPI:

Called by root.

bmif_get_time_units()

integer function BMIPhreeqcRM::bmif_get_time_units	(	class(bmi), intent(inout)	self,
		character(len=*), intent(inout)	time_units
	)

bmif_get_time_units returns the time units of PhreeqcRM. All time units are seconds for PhreeqcRM.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
time_units	Returns the string "seconds".

Return values

0	is success, 1 is failure.

See also

bmif_get_current_time, bmif_get_end_time, bmif_get_time_step, bmi::bmif_set_value, GetTime, GetTimestep, SetTime, SetTimeStep, bmi::bmif_set_value.

Fortran example:

 character(20) time_units
 status = brm%bmif_get_time_units(time_units)
 

MPI:

Called by root.

bmif_get_value_char()

integer function BMIPhreeqcRM::bmif_get_value_char	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		character(len=*), intent(inout)	dest
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_char1()

integer function BMIPhreeqcRM::bmif_get_value_char1	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		character(len=:), dimension(:), intent(inout), allocatable	dest
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_char_alloc()

integer function BMIPhreeqcRM::bmif_get_value_char_alloc	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		character(len=:), intent(inout), allocatable	dest
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_double()

integer function BMIPhreeqcRM::bmif_get_value_double	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		real(kind=8), intent(inout)	dest
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_double1()

integer function BMIPhreeqcRM::bmif_get_value_double1	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		real(kind=8), dimension(:), intent(inout), allocatable	dest
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_double2()

integer function BMIPhreeqcRM::bmif_get_value_double2	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		real(kind=8), dimension(:,:), intent(inout), allocatable	dest
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_int()

integer function BMIPhreeqcRM::bmif_get_value_int	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		integer, intent(inout)	dest
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_int1()

integer function BMIPhreeqcRM::bmif_get_value_int1	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		integer, dimension(:), intent(inout), allocatable	dest
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_int2()

integer function BMIPhreeqcRM::bmif_get_value_int2	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		integer, dimension(:,:), intent(inout), allocatable	dest
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_logical()

integer function BMIPhreeqcRM::bmif_get_value_logical	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		logical, intent(inout)	dest
	)

bmif_get_value retrieves model variables. Only variables in the list provided by bmif_get_output_var_names can be retrieved.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
var	Name of the variable to retrieve.
dest	Variable in which to place results.

Return values

0	is success, 1 is failure.

Variable names for the second argument (name) and variable type of the third argument (dest).
"ComponentCount", dest: integer;
"Components", dest: character(len=:), allocatable, dimension(:);
"Concentrations", dest: real(kind=8), allocatable, dimension(:,:);
"CurrentSelectedOutputUserNumber", dest: integer;
"DensityCalculated", dest: real(kind=8), allocatable, dimension(:);
"ErrorString", dest: character;
"FilePrefix", dest: character;
"Gfw", dest: real(kind=8), allocatable, dimension(:);
"GridCellCount", dest: integer;
"Porosity", dest: real(kind=8), allocatable, dimension(:);
"Pressure", dest: real(kind=8), allocatable, dimension(:);
"SaturationCalculated", dest: real(kind=8), allocatable, dimension(:);
"SelectedOutput", dest: real(kind=8), allocatable, dimension(:,:);
"SelectedOutputColumnCount", dest: integer;
"SelectedOutputCount", dest: integer;
"SelectedOutputHeadings", dest: character(len=:), allocatable, dimension(:);
"SelectedOutputOn", dest: logical;
"SelectedOutputRowCount", dest: integer;
"SolutionVolume", dest: real(kind=8), allocatable, dimension(:);
"Temperature", dest: real(kind=8), allocatable, dimension(:);
"Time", dest: real(kind=8);
"TimeStep", dest: real(kind=8);
"Viscosity", dest: real(kind=8), allocatable, dimension(:).

See also

bmif_get_output_var_names, bmif_get_output_item_count, bmif_get_var_itemsize, bmif_get_var_nbytes, bmif_get_var_type, bmif_get_var_units, bmi::bmif_set_value.

Fortran example:

 real(kind=8), allocatable, dimension(:) :: bmi_density
 character(len=:), allocatable, dimension(:) :: bmi_comps
 status = brm%bmif_get_value("DensityCalculated", bmi_density)
 status = brm%bmif_get_value("Components", bmi_comps)
 

MPI:

Called by root, workers must be in the loop of MpiWorker. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_ptr_double()

integer function BMIPhreeqcRM::bmif_get_value_ptr_double	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		real(kind=c_double), intent(inout), pointer	ptr
	)

bmif_get_value_ptr retrieves pointers to model variables. Only variables in the list provided by bmif_get_pointable_var_names can be pointed to.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
var	Name of the variable to retrieve.
ptr	Pointer to the variable's data.

Return values

0	is success, 1 is failure.

The following list gives the name in the second argument (var) and the data type the pointer (ptr):

"ComponentCount": integer;
"Concentrations": real(kind=8) (:);
"DensityCalculated": real(kind=8) (:);
"Gfw": real(kind=8) (:);
"GridCellCount": integer;
"Porosity": real(kind=8) (:);
"Pressure": real(kind=8) (:);
"SaturationCalculated": real(kind=8) (:);
"SelectedOutputOn": logical(kind=1);
"SolutionVolume": real(kind=8) (:);
"Temperature": real(kind=8) (:);
"Time": real(kind=8);
"TimeStep": real(kind=8);
"Viscosity": real(kind=8) (:);

MPI:

Called by root, workers must be in the loop of MpiWorker.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_ptr_double1()

integer function BMIPhreeqcRM::bmif_get_value_ptr_double1	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		real(kind=c_double), dimension(:), intent(inout), pointer	ptr
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_ptr_integer()

integer function BMIPhreeqcRM::bmif_get_value_ptr_integer	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		integer, intent(inout), pointer	ptr
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_value_ptr_logical()

integer function BMIPhreeqcRM::bmif_get_value_ptr_logical	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		logical(kind=1), intent(inout), pointer	ptr
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_get_var_grid()

integer function BMIPhreeqcRM::bmif_get_var_grid	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		integer, intent(out)	grid
	)

bmif_get_var_grid returns a value of 1, indicating points. BMIPhreeqcRM does not have a grid of its own. The cells of BMIPhreeqcRM are associated with the user's model grid, and all spatial characterists are assigned by the user's model.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
var	Varaiable name. (Return value is the same regardless of var.)
grid	1 (points). BMIPhreeqcRM cells derive meaning from the user's model.

Return values

0	is success, 1 is failure.

bmif_get_var_itemsize()

integer function BMIPhreeqcRM::bmif_get_var_itemsize	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		integer, intent(out)	itemsize
	)

bmif_get_var_itemsize retrieves the size, in bytes, of a variable that can be set with bmi::bmif_set_value, retrieved with bmi::bmif_get_value, or pointed to with bmi::bmif_get_value_ptr. Sizes may be the size of an integer, real(kind=8), or a character length for string variables.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
var	Name of the variable to retrieve the item size.
itemsize	Size, in bytes, of one element of the variable.

Return values

0	is success, 1 is failure.

See also

bmif_get_input_var_names, bmif_get_input_item_count, bmif_get_output_var_names, bmif_get_output_item_count, bmif_get_pointable_var_names, bmif_get_pointable_item_count, bmi::bmif_get_value, bmi::bmif_get_value_ptr, bmif_get_var_nbytes, bmif_get_var_type, bmif_get_var_units, bmi::bmif_set_value.

Fortran example:

 integer nbytes, item_size, dim
 real(kind=8), allocatable, dimension(:) :: bmi_temperature
 status = brm%bmif_get_var_nbytes("Temperature", nbytes)
 status = brm%bmif_get_var_itemsize("Temperature", item_size)
 dim    = nbytes/item_size
 allocate(bmi_temperature(dim))
 bmi_temperature = 25.0
 status = brm%bmif_set_value("Temperature", bmi_temperature)
 

MPI:

Called by root.

bmif_get_var_nbytes()

integer function BMIPhreeqcRM::bmif_get_var_nbytes	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		integer, intent(out)	nbytes
	)

bmif_get_var_nbytes retrieves the total number of bytes needed for a variable that can be set with bmi::bmif_set_value, retrieved with bmi::bmif_get_value, or pointed to with bmi::bmif_get_value_ptr.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
var	Name of the variable to retrieve the number of bytes needed to retrieve or store the variable.
nbytes	Total number of bytes needed for the variable.

Return values

0	is success, 1 is failure.

See also

bmif_get_input_var_names, bmif_get_input_item_count, bmif_get_output_var_names, bmif_get_output_item_count, bmif_get_pointable_var_names, bmif_get_pointable_item_count, bmi::bmif_get_value, bmi::bmif_get_value_ptr, bmif_get_var_itemsize, bmif_get_var_type, bmif_get_var_units, bmi::bmif_set_value.

Fortran example:

 integer nbytes, item_size, dim
 real(kind=8), allocatable, dimension(:) :: bmi_temperature
 status = brm%bmif_get_var_nbytes("Temperature", nbytes)
 status = brm%bmif_get_var_itemsize("Temperature", item_size)
 dim    = nbytes/item_size
 allocate(bmi_temperature(dim))
 bmi_temperature = 25.0
 status = brm%bmif_set_value("Temperature", bmi_temperature)
 

MPI:

Called by root.

bmif_get_var_type()

integer function BMIPhreeqcRM::bmif_get_var_type	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		character(len=*), intent(inout)	vtype
	)

bmif_get_var_type retrieves the type of a variable that can be set with bmi::bmif_set_value, retrieved with bmi::bmif_get_value, or pointed to with bmi::bmif_get_value_ptr. Types are "character", "real(kind=8)", "integer", or "logical", or an allocatable array of these types.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
var	Name of the variable to retrieve the type.
vtype	Type of the variable.

Return values

0	is success, 1 is failure.

See also

bmif_get_input_var_names, bmif_get_input_item_count, bmif_get_output_var_names, bmif_get_output_item_count, bmif_get_pointable_var_names, bmif_get_pointable_item_count, bmi::bmif_get_value, bmi::bmif_get_value_ptr, bmif_get_var_itemsize, bmif_get_var_nbytes, bmif_get_var_units, bmi::bmif_set_value.

Fortran example:

 do i = 1, size(inputvars)
     write(*,"(1x, I4, A40)") i, trim(inputvars(i))
     status = brm%bmif_get_var_units(inputvars(i), string)
     write(*,"(5x, A15)") trim(string)
     status = brm%bmif_get_var_type(inputvars(i), string)
     write(*,"(5x, A15)") trim(string)
     status = brm%bmif_get_var_itemsize(inputvars(i), itemsize)
     write(*, "(5x, I15)") itemsize
     status = brm%bmif_get_var_nbytes(inputvars(i), nbytes)
     write(*, "(5x, I15)") nbytes
 enddo
 

MPI:

Called by root.

bmif_get_var_units()

integer function BMIPhreeqcRM::bmif_get_var_units	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		character(len=*), intent(inout)	units
	)

bmif_get_var_units retrieves the units of a variable that can be set with bmi::bmif_set_value, retrieved with bmi::bmif_get_value, or pointed to with bmi::bmif_get_value_ptr.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
var	Name of the variable to retrieve units.
units	Units of the variable.

Return values

0	is success, 1 is failure.

See also

bmif_get_input_var_names, bmif_get_input_item_count, bmif_get_output_var_names, bmif_get_output_item_count, bmif_get_pointable_var_names, bmif_get_pointable_item_count, bmi::bmif_get_value, bmi::bmif_get_value_ptr, bmif_get_var_itemsize, bmif_get_var_nbytes, bmif_get_var_type, bmi::bmif_set_value.

Fortran example:

 do i = 1, size(inputvars)
     write(*,"(1x, I4, A40)") i, trim(inputvars(i))
     status = brm%bmif_get_var_units(inputvars(i), string)
     write(*,"(5x, A15)") trim(string)
     status = brm%bmif_get_var_type(inputvars(i), string)
     write(*,"(5x, A15)") trim(string)
     status = brm%bmif_get_var_itemsize(inputvars(i), itemsize)
     write(*, "(5x, I15)") itemsize
     status = brm%bmif_get_var_nbytes(inputvars(i), nbytes)
     write(*, "(5x, I15)") nbytes
 enddo
 

MPI:

Called by root.

bmif_grid_rank()

integer function BMIPhreeqcRM::bmif_grid_rank	(	class(bmi), intent(inout)	self,
		integer, intent(in)	grid,
		integer, intent(inout)	rank
	)

bmif_get_grid_rank returns a rank of 1 for grid 0. BMIPhreeqcRM has a 1D series of cells; any grid or spatial information must be found in the user's model.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
grid	Grid number, only grid 0 is considered.
rank	Rank of 1 is returned for grid 0; 0 for all other values of grid.

Return values

0	is success, 1 is failure.

Fortran example:

 status = brm%bmif_grid_rank(grid, rank)
 

MPI:

Called by root.

bmif_grid_size()

integer function BMIPhreeqcRM::bmif_grid_size	(	class(bmi), intent(inout)	self,
		integer, intent(in)	grid,
		integer, intent(inout)	ngrid
	)

bmif_grid_size returns the number of cells specified at creation of the BMIPhreeqcRM instance.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
grid	Grid number, only grid 0 is considered.
ngrid	Same value as GetGridCellCount or GridCellCount is returned for grid 0; 0 for all other values of grid.

Return values

0	is success, 1 is failure.

Fortran example:

 status = brm%bmif_grid_size(grid, ngrid)
 

MPI:

Called by root.

bmif_grid_type()

integer function BMIPhreeqcRM::bmif_grid_type	(	class(bmi), intent(inout)	self,
		integer, intent(in)	grid,
		character(len=*), intent(inout)	str
	)

bmif_grid_type defines the grid to be points. No grid information is available in BMIPhreeqcRM; all grid information must be found in the user's model.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
grid	Grid number, only grid 0 is considered.
str	"Points" is returned for grid 0; "Undefined grid identifier" is returned for all other values of grid.

Return values

0	is success, 1 is failure.

Fortran example:

 status = brm%bmif_grid_type(grid, str)
 

MPI:

Called by root.

bmif_initialize()

integer function BMIPhreeqcRM::bmif_initialize	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	config_file
	)

bmif_initialize must be called to initialize a BMIPhreeqcRM instance. A YAML file is normally used for initialization; however, an empty string can be used for the file name when initializing without use of a YAML file.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
config_file	String containing the YAML file name; use an empty string for initialization without using a YAML file.

Return values

0	is success, 1 is failure.

The file contains a YAML map of PhreeqcRM methods and the arguments corresponding to the methods. Note that the PhreeqcRM methods do not have the "RM_" prefix and the id argument is not included. For example,

  key: LoadDatabase
   database: phreeqc.dat
 - key: RunFile
 workers: true
 initial_phreeqc: true
   utility: true
  chemistry_name: advect.pqi
 

bmif_initialize will read the YAML file and execute the specified methods with the specified arguments. Using YAML terminology, the argument(s) for a method may be a scalar, a sequence, or a map, depending if the argument is a single item, a single vector, or there are multiple arguments. In the case of a map, the name associated with each argument (for example "chemistry_name" above) is arbitrary. The names of the map keys for map arguments are not used in parsing the YAML file; only the order of the arguments is important.

The following list gives the PhreeqcRM methods that can be specified in a YAML file and the arguments that are required. The arguments are described with C++ formats, which are sufficient to identify which arguments are YAML scalars (single bool/logical, int, double, string/character argument), sequences (single vector argument), or maps (multiple arguments).

 CloseFiles();
 CreateMapping(std::vector< int >& grid2chem);
 DumpModule();
 FindComponents();
 InitialEquilibriumPhases2Module(std::vector< int > equilibrium_phases);
 InitialExchanges2Module(std::vector< int > exchanges);
 InitialGasPhases2Module(std::vector< int > gas_phases);
 InitialKineticss2Module(std::vector< int > kinetics);
 InitialSolidSolutions2Module(std::vector< int > solid_solutions);
 InitialSolutions2Module(std::vector< int > solutions);
 InitialSurfaces2Module(std::vector< int > surfaces);
 InitialPhreeqc2Module(std::vector< int > initial_conditions1);
 InitialPhreeqc2Module(std::vector< int > initial_conditions1, 
 std::vector< int > initial_conditions2, std::vector< double > fraction1);
 InitialPhreeqcCell2Module(int n, std::vector< int > cell_numbers);
 LoadDatabase(std::string database);
 OpenFiles();
 OutputMessage(std::string str);
 RunCells();
 RunFile(bool workers, bool initial_phreeqc, bool utility, std::string chemistry_name);
 RunString(bool workers, bool initial_phreeqc, bool utility, std::string input_string);
 ScreenMessage(std::string str);
 SetComponentH2O(bool tf);
 SetConcentrations(std::vector< double > c);
 SetCurrentSelectedOutputUserNumber(int n_user);
 SetDensityUser(std::vector< double > density);
 SetDumpFileName(std::string dump_name);
 SetErrorHandlerMode(int mode);
 SetErrorOn(bool tf);
 SetFilePrefix(std::string prefix);
 SetGasCompMoles(std::vector< double > gas_moles);
 SetGasPhaseVolume(std::vector< double > gas_volume);
 SetPartitionUZSolids(bool tf);
 SetPorosity(std::vector< double > por);
 SetPressure(std::vector< double > p);
 SetPrintChemistryMask(std::vector< int > cell_mask);
 SetPrintChemistryOn(bool workers, bool initial_phreeqc, bool utility);
 SetRebalanceByCell(bool tf);
 SetRebalanceFraction(double f);
 SetRepresentativeVolume(std::vector< double > rv);
 SetSaturationUser(std::vector< double > sat);
 SetScreenOn(bool tf);
 SetSelectedOutputOn(bool tf);
 SetSpeciesSaveOn(bool save_on);
 SetTemperature(std::vector< double > t);
 SetTime(double time);
 SetTimeConversion(double conv_factor);
 SetTimeStep(double time_step);
 SetUnitsExchange(int option);
 SetUnitsGasPhase(int option);
 SetUnitsKinetics(int option);
 SetUnitsPPassemblage(int option);
 SetUnitsSolution(int option);
 SetUnitsSSassemblage(int option);
 SetUnitsSurface(int option);
 SpeciesConcentrations2Module(std::vector< double > species_conc);
 StateSave(int istate);
 StateApply(int istate);
 StateDelete(int istate);
 UseSolutionDensityVolume(bool tf);
 WarningMessage(std::string warnstr);
 

Fortran example:

 id = brm%bmif_create(nxyz, nthreads)
 status = brm%bmif_initializeYAML("myfile.yaml")
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

bmif_set_value_b()

integer function BMIPhreeqcRM::bmif_set_value_b	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		logical, intent(in)	src
	)

bmif_set_value sets model variables. Only variables in the list provided by bmif_get_input_var_names can be set.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
var	Name of variable to set.
src	Data to use to set the variable.

Return values

0	is success, 1 is failure.

Variable names for the second argument (var) and required variable type for the third argument (src):
"Concentrations", real(kind=8), allocatable, dimension(:,:);
"DensityUser", real(kind=8), allocatable, dimension(:);
"FilePrefix", character;
"NthSelectedOutput", integer;
"Porosity", real(kind=8), allocatable, dimension(:);
"Pressure", real(kind=8), allocatable, dimension(:);
"SaturationUser", real(kind=8), allocatable, dimension(:);
"SelectedOutputOn", logical;
"Temperature", real(kind=8), allocatable, dimension(:);
"Time", real(kind=8);
"TimeStep", real(kind=8).

See also

bmif_get_input_var_names, bmif_get_input_item_count,, bmi::bmif_get_value, bmif_get_var_itemsize, bmif_get_var_nbytes, bmif_get_var_type, bmif_get_var_units.

Fortran example:

 real(kind=8), allocatable, dimension(:) :: tc
 allocate(tc(nxyz))
 tc = 28.0d0
 status = brm%bmif_set_value("Temperature", tc)
 

MPI:

Called by root, workers must be in the loop of MpiWorker. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_set_value_c()

integer function BMIPhreeqcRM::bmif_set_value_c	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		character(len=*), intent(in)	src
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_set_value_double()

integer function BMIPhreeqcRM::bmif_set_value_double	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		real(kind=8), intent(in)	src
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_set_value_double1()

integer function BMIPhreeqcRM::bmif_set_value_double1	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		real(kind=8), dimension(:), intent(in)	src
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_set_value_double2()

integer function BMIPhreeqcRM::bmif_set_value_double2	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		real(kind=8), dimension(:,:), intent(in)	src
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_set_value_int()

integer function BMIPhreeqcRM::bmif_set_value_int	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		integer, intent(in)	src
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_set_value_int1()

integer function BMIPhreeqcRM::bmif_set_value_int1	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		integer, dimension(:), intent(in)	src
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_set_value_int2()

integer function BMIPhreeqcRM::bmif_set_value_int2	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	var,
		integer, dimension(:,:), intent(in)	src
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bmif_update()

integer function BMIPhreeqcRM::bmif_update

(

class(bmi), intent(inout)

self

)

bmif_update runs a reaction step for all of the cells in the reaction module. Same as RunCells.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

0

is success, 1 is failure. Tranport concentrations are transferred to the reaction cells (Concentrations before reaction calculations are run. The length of time over which kinetic reactions are integrated is set by TimeStep. Other properties that may need to be updated as a result of the transport calculations include porosity (Porosity), pressure (Pressure), saturation (SaturationUser), temperature (Temperature).

See also

bmi::bmif_get_value, bmi::bmif_set_value.

Fortran example:

 status = brm%bmif_set_value("Porosity", por)                ! If pore volume changes
 status = brm%bmif_set_value("SaturationUser", sat)              ! If saturation changes
 status = brm%bmif_set_value("Temperature", temperature)     ! If temperature changes
 status = brm%bmif_set_value("Pressure", pressure)           ! If pressure changes
 status = brm%bmif_set_value("Concentrations", c)            ! Transported concentrations
 status = brm%bmif_set_value("TimeStep", time_step)          ! Time step for kinetic reactions
 status = brm%bmif_update()
 status = brm%bmif_get_value("Concentrations", c)            ! Concentrations after reaction
 status = brm%bmif_get_value("DensityCalculated", density)   ! Density after reaction
 status = brm%bmif_get_value("SolutionVolume", volume)       ! Solution volume after reaction
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

bmif_update_until()

integer function BMIPhreeqcRM::bmif_update_until	(	class(bmi), intent(in)	self,
		real(kind=8), intent(in)	end_time
	)

bmif_update_until is the same as bmif_update, except the time step is calculated from the argument end_time. The time step is calculated to be end_time minus the current time (bmif_get_current_time).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance..
end_time	Time at the end of the time step.

See also

bmif_initialize, bmif_update.

Fortran example:

 status = brm%bmif_set_value("Time", time)
 status = brm%bmif_set_value("Concentrations", c)
 status = brm%bmif_update_until(time + 86400.0)
 status = brm%bmif_get_value("Concentrations", c)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

CloseFiles()

integer function BMIPhreeqcRM::CloseFiles

(

class(bmi), intent(inout)

self

)

Close the output and log files.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

OpenFiles, SetFilePrefix.

Fortran Example:

 status = brm%CloseFiles()
 

MPI:

Called only by root.

Concentrations2Utility()

integer function BMIPhreeqcRM::Concentrations2Utility	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(in)	c,
		integer, intent(in)	n,
		real(kind=8), dimension(:), intent(in)	tc,
		real(kind=8), dimension(:), intent(in)	p_atm
	)

N sets of component concentrations are converted to SOLUTIONs numbered 1-n in the Utility IPhreeqc. The solutions can be reacted and manipulated with the methods of IPhreeqc. If solution concentration units (SetUnitsSolution) are per liter, one liter of solution is Created in the Utility instance; if solution concentration units are mass fraction, one kilogram of solution is Created in the Utility instance. The motivation for this method is the mixing of solutions in wells, where it may be necessary to calculate solution properties (pH for example) or react the mixture to form scale minerals. The code fragments below make a mixture of concentrations and then calculate the pH of the mixture.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
c	Array of concentrations to be made SOLUTIONs in Utility IPhreeqc, array size is (n, ncomps) where ncomps is the number of components (GetComponentCount).
n	The number of sets of concentrations.
tc	Array of temperatures to apply to the SOLUTIONs, in degree C. Array of size n.
p_atm	Array of pressures to apply to the SOLUTIONs, in atm. Array of size n.

Return values

id	number of the utility IPhreeqc instance.

Fortran Example:

 allocate (c_well(1,ncomps))
 do i = 1, ncomps
   c_well(1,i) = 0.5 * c(1,i) + 0.5 * c(10,i)
 enddo
 allocate(tc(1), p_atm(1))
 tc(1) = 15.0
 p_atm(1) = 3.0
 iphreeqc_id = brm%Concentrations2Utility(c_well, 1, tc, p_atm)
 string = "SELECTED_OUTPUT 5; -pH; RUN_CELLS; -cells 1"
 status = brm%RunString(iphreeqc_id, string)
 status = brm%SetCurrentSelectedOutputUserNumber(iphreeqc_id, 5)
 status = brm%GetSelectedOutputValue(iphreeqc_id, 1, 1, vtype, pH, svalue)
 

MPI:

Called only by root.

CreateMapping()

integer function BMIPhreeqcRM::CreateMapping	(	class(bmi), intent(inout)	self,
		integer, dimension(:), intent(in)	grid2chem
	)

Provides a mapping from grid cells in the user's model to reaction cells in PhreeqcRM. The mapping is used to eliminate inactive cells and to use symmetry to decrease the number of cells for which chemistry must be run. The array grid2chem of size nxyz (the number of grid cells, GetGridCellCount) must contain the set of all integers 0 <= i < count_chemistry, where count_chemistry is a number less than or equal to nxyz. Inactive cells are assigned a negative integer. The mapping may be many-to-one to account for symmetry. Default is a one-to-one mapping–all user grid cells are reaction cells (equivalent to grid2chem values of 0,1,2,3,...,nxyz-1).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
grid2chem	An array of integers: Nonnegative is a reaction cell number (0 based), negative is an inactive cell. Array of size nxyz (number of grid cells).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

Fortran Example:

 ! For demonstation, two equivalent rows by symmetry
 allocate(grid2chem(nxyz))
 do i = 1, nxyz/2
   grid2chem(i) = i - 1
   grid2chem(i+nxyz/2) = i - 1
 enddo
 status = brm%CreateMapping(grid2chem)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

DecodeError()

integer function BMIPhreeqcRM::DecodeError	(	class(bmi), intent(inout)	self,
		integer, intent(in)	e
	)

If e is negative, this method prints an error message corresponding to IRESULT e. If e is non-negative, no action is taken.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
e	An IRESULT value returned by one of the reaction-module methods.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

IRESULT definition:

 typedef enum {
   IOK            =  0,  ! Success
   IOUTOFMEMORY   = -1,  ! Failure, Out of memory
   IBADVARTYPE    = -2,  ! Failure, Invalid VAR type
   IINVALIDARG    = -3,  ! Failure, Invalid argument
   IINVALIDROW    = -4,  ! Failure, Invalid row
   IINVALIDCOL    = -5,  ! Failure, Invalid column
   IBADINSTANCE   = -6,  ! Failure, Invalid rm instance id
   IFAIL          = -7,  ! Failure, Unspecified
 } IRESULT;
 

Fortran Example:

 status = brm%CreateMapping(grid2chem)
 if (status < 0) status = brm%DecodeError(status)
 

MPI:

Can be called by root and (or) workers.

Destroy()

integer function BMIPhreeqcRM::Destroy

(

class(bmi), intent(inout)

self

)

Destroys a reaction module.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

bmif_create.

Fortran Example:

 status = brm%Destroy()
 

MPI:

Called by root and workers.

DumpModule()

integer function BMIPhreeqcRM::DumpModule	(	class(bmi), intent(inout)	self,
		integer, intent(in)	dump_on,
		integer, intent(in)	append
	)

Writes the contents of all workers to file in _RAW formats, including SOLUTIONs and all reactants.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
dump_on	Signal for writing the dump file: 1 true, 0 false.
append	Signal to append to the contents of the dump file: 1 true, 0 false.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetDumpFileName.

Fortran Example:

      
 dump_on = 1
 append = 0
 status = brm%SetDumpFileName("advection_f90.dmp")
 status = brm%DumpModule(dump_on, append)
 

MPI:

Called by root; workers must be in the loop of MpiWorker.

ErrorMessage()

integer function BMIPhreeqcRM::ErrorMessage	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	errstr
	)

Send an error message to the screen, the output file, and the log file.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
errstr	String to be printed.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

LogMessage, OpenFiles, OutputMessage, ScreenMessage, WarningMessage.

Fortran Example:

 status = brm%ErrorMessage("Goodbye world")
 

MPI:

Called by root and (or) workers; root writes to output and log files.

FindComponents()

integer function BMIPhreeqcRM::FindComponents

(

class(bmi), intent(inout)

self

)

Returns the number of items in the list of all elements in the InitialPhreeqc instance. Elements are those that have been defined in a solution or any other reactant (EQUILIBRIUM_PHASE, KINETICS, and others). The method can be called multiple times and the list that is Created is cummulative. The list is the set of components that needs to be transported. By default the list includes water, excess H and excess O (the H and O not contained in water); alternatively, the list may be set to contain total H and total O (SetComponentH2O), which requires transport results to be accurate to eight or nine significant digits. If multicomponent diffusion (MCD) is to be modeled, there is a capability to retrieve aqueous species concentrations (GetSpeciesConcentrations) and to set new solution concentrations after MCD by using individual species concentrations (SpeciesConcentrations2Module). To use these methods the save-species property needs to be turned on (SetSpeciesSaveOn). If the save-species property is on, FindComponents will generate a list of aqueous species (GetSpeciesCount, GetSpeciesNames), their diffusion coefficients at 25 C (GetSpeciesD25), their charge (GetSpeciesZ).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

Number

of components currently in the list, or IRESULT error code (see DecodeError).

The FindComponents method also generates lists of reactants–equilibrium phases, exchangers, gas components, kinetic reactants, solid solution components, and surfaces. The lists are cumulative, including all reactants that were defined in the initial phreeqc instance at any time FindComponents was called. In addition, a list of phases is generated for which saturation indices may be calculated from the cumulative list of components.

See also

SetComponentH2O, GetComponents, GetEquilibriumPhasesNames, GetEquilibriumPhasesCount, GetExchangeNames, GetExchangeSpeciesNames, GetExchangeSpeciesCount, GetGasComponentsNames, GetGasComponentsCount, GetKineticReactionsNames, GetKineticReactionsCount, GetSICount, GetSINames, GetSolidSolutionComponentsNames, GetSolidSolutionComponentsCount, GetSolidSolutionNames, GetSpeciesConcentrations, GetSpeciesCount, GetSpeciesD25, GetSpeciesLog10Gammas, GetSpeciesLog10Molalities, GetSpeciesNames, GetSpeciesZ, GetSurfaceNames, GetSurfaceSpeciesNames, GetSurfaceSpeciesCount, GetSurfaceTypes, SetSpeciesSaveOn.

Fortran Example:

 character(len=:), allocatable :: components(:)
 ncomps = brm%FindComponents()
 status = brm%GetComponents(components)
 enddo
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetBackwardMapping()

integer function BMIPhreeqcRM::GetBackwardMapping	(	class(bmi), intent(inout)	self,
		integer, intent(in)	n,
		integer, dimension(:), intent(inout), allocatable	list
	)

Fills an array with the cell numbers in the user's numbering sytstem that map to a cell in the PhreeqcRM numbering system. The mapping is defined by CreateMapping.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
n	A cell number in the PhreeqcRM numbering system (0 <= n < GetChemistryCellCount).
list	Allocatable array to store the user cell numbers mapped to PhreeqcRM cell n.

Return values

IRESULT

error code (see DecodeError).

See also

CreateMapping, GetChemistryCellCount, GetGridCellCount.

C Example:

 if (brm%GetBackwardMapping(cell_number, list) .eq. 0) then
   if (fstr(1:l) .eq. "HYDRAULIC_K") then
     my_basic_fortran_callback = K_ptr(list(1)+1)
   endif
 endif
 

MPI:

Called by root and (or) workers.

GetChemistryCellCount()

integer function BMIPhreeqcRM::GetChemistryCellCount

(

class(bmi), intent(inout)

self

)

Returns the number of chemistry cells in the reaction module. The number of chemistry cells is defined by the set of non-negative integers in the mapping from user grid cells (CreateMapping). The number of chemistry cells is less than or equal to the number of cells in the user's model.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

Number

of chemistry cells, or IRESULT error code (see DecodeError).

See also

CreateMapping, GetGridCellCount.

Fortran Example:

 status = brm%CreateMapping(grid2chem)
 nchem = brm%GetChemistryCellCount()
 

MPI:

Called by root and (or) workers.

GetComponentCount()

integer function BMIPhreeqcRM::GetComponentCount

(

class(bmi), intent(inout)

self

)

PRIVATE Returns the number of components in the reaction-module component list. The component list is generated by calls to FindComponents. The return value from the last call to FindComponents is equal to the return value from GetComponentCount.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	number of components in the reaction-module component list, negative is failure (See DecodeError).

See also

FindComponents, GetComponents.

Fortran Example:

 ncomps1 = brm%GetComponentCount()
 

MPI:

Called by root.

GetComponents()

integer function BMIPhreeqcRM::GetComponents	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	components
	)

Returns a list of the names of the components identified by PhreeqcRM. The list contains all components (elements) found in solutions and reactants in the InitialPhreeqc instance by call(s) to FindComponents.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
components	Allocatable, 1D character variable to receive the component names.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents.

Fortran Example:

 character(len=:), allocatable :: components(:)
 status = brm%GetComponents(components)
 

MPI:

Called by root.

GetConcentrations()

integer function BMIPhreeqcRM::GetConcentrations	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(inout), allocatable	c
	)

Transfer solution concentrations from each reaction cell to the concentration array given in the argument list (c). Units of concentration for c are defined by SetUnitsSolution. For concentration units of per liter, the solution volume is used to calculate the concentrations for c. For mass fraction concentration units, the solution mass is used to calculate concentrations for c. Two options are available for the volume and mass of solution that are used in converting to transport concentrations: (1) the volume and mass of solution are calculated by PHREEQC, or (2) the volume of solution is the product of saturation (SetSaturationUser), porosity (SetPorosity), and representative volume (SetRepresentativeVolume), and the mass of solution is volume times density as defined by SetDensityUser. UseSolutionDensityVolume determines which option is used. For option 1, the databases that have partial molar volume definitions needed to calculate solution volume accurately are phreeqc.dat, Amm.dat, and pitzer.dat.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
c	Array to receive the concentrations. Dimension of the array will be set to (nxyz, ncomps), where nxyz is the number of user grid cells and ncomps is the result of FindComponents or GetComponentCount. Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetComponentCount, GetDensityCalculated, GetSaturationCalculated, SetConcentrations, SetDensityUser, SetRepresentativeVolume, SetSaturationUser, SetUnitsSolution, UseSolutionDensityVolume.

Fortran Example:

 real(kind=8), allocatable :: c(:,:)
 status = brm%RunCells()
 status = brm%GetConcentrations(c)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetCurrentSelectedOutputUserNumber()

integer function BMIPhreeqcRM::GetCurrentSelectedOutputUserNumber

(

class(bmi), intent(inout)

self

)

Returns the user number of the current selected-output definition. SetCurrentSelectedOutputUserNumber or SetNthSelectedOutput specifies which of the selected-output definitions is used.

Return values

User	number of the the current selected-output definition, negative is failure (See DecodeError).

See also

GetNthSelectedOutputUserNumber, GetSelectedOutput, GetSelectedOutputColumnCount, GetSelectedOutputCount, GetSelectedOutputHeadings, GetSelectedOutputRowCount, SetCurrentSelectedOutputUserNumber, SetNthSelectedOutput, SetSelectedOutputOn.

Fortran Example:

 do isel = 1, brm%GetSelectedOutputCount()
   status = brm%SetNthSelectedOutput(isel)
   n_user = brm%GetCurrentSelectedOutputUserNumber()
   col = brm%GetSelectedOutputColumnCount()
   allocate(selected_out(nxyz,col))
   status = brm%GetSelectedOutput(selected_out)
   ! Process results here
   deallocate(selected_out)
 enddo
 

MPI:

Called by root.

GetDensity()

integer function BMIPhreeqcRM::GetDensity	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	density
	)

This deprecated function is included for backward compatibility. Use GetDensityCalculated.

GetDensityCalculated()

integer function BMIPhreeqcRM::GetDensityCalculated	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	density
	)

Transfer solution densities from the reaction cells to the array given in the argument list (density). Densities are those calculated by the reaction module. This method always returns the calculated densities; SetDensityUser does not affect the result. Only the following databases distributed with PhreeqcRM have molar volume information needed to accurately calculate density: phreeqc.dat, Amm.dat, and pitzer.dat.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
density	Allocatable array to receive the densities. Dimension of the array is set to nxyz, where nxyz is the number of user grid cells (GetGridCellCount). Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

Fortran Example:

 real(kind=8), allocatable :: density(:)
 status = brm%RunCells()
 status = brm%GetDensityCalculated(density)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetEndCell()

integer function BMIPhreeqcRM::GetEndCell	(	class(bmi), intent(inout)	self,
		integer, dimension(:), intent(inout), allocatable	ec
	)

Returns an array with the ending cell numbers from the range of cell numbers assigned to each worker.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
ec	Array to receive the ending cell numbers. Dimension of the array is the number of threads (OpenMP) or the number of processes (MPI).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

bmif_create, GetMpiTasks, GetStartCell, GetThreadCount.

Fortran Example:

 integer, allocatable :: ec(:)
 status = brm%GetEndCell(ec)
 

MPI:

Called by root and (or) workers.

GetEquilibriumPhasesCount()

integer function BMIPhreeqcRM::GetEquilibriumPhasesCount

(

class(bmi), intent(inout)

self

)

Returns the number of equilibrium phases in the initial-phreeqc module. FindComponents must be called before GetEquilibriumPhasesCount. This method may be useful when generating selected output definitions related to equilibrium phases.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	number of equilibrium phases in the initial-phreeqc module.

See also

FindComponents, GetEquilibriumPhasesNames.

Fortran Example:

 character(len=:), allocatable :: names(:)
 status = brm%GetEquilibriumPhasesNames(names)
 do i = 1, brm%GetEquilibriumPhasesCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetEquilibriumPhasesNames()

integer function BMIPhreeqcRM::GetEquilibriumPhasesNames	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Retrieve a list of equilibrium phase names. The list includes all phases included in any EQUILIBRIUM_PHASES definitions in the initial-phreeqc module. FindComponents must be called before GetEquilibriumPhasesNames. This method may be useful when generating selected output definitions related to equilibrium phases.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Array of equilibrium phase names.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetEquilibriumPhasesCount.

Fortran Example:

 status = brm%GetEquilibriumPhasesNames(names)
 do i = 1, brm%GetEquilibriumPhasesCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetErrorString()

integer function BMIPhreeqcRM::GetErrorString	(	class(bmi), intent(inout)	self,
		character(len=:), intent(inout), allocatable	errstr
	)

Returns a string containing error messages related to the last call to a PhreeqcRM method to the character argument (errstr).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
errstr	The error string related to the last call to a PhreeqcRM method.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

Fortran Example:

 character(len=:), allocatable :: errstr
 if (status .lt. 0) then
   status = brm%GetErrorString(errstr)
   write(*,"(A)") errstr
   status = brm%Destroy()
   stop
 endif 
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetExchangeNames()

integer function BMIPhreeqcRM::GetExchangeNames	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Retrieves a list of exchange names. FindComponents must be called before GetExchangeNames. The exchange names array is the same length as the exchange species names array and provides the corresponding exchange site (for example, X corresponing to NaX). This method may be useful when generating selected output definitions related to exchangers.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Allocatable array of exchange names.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetExchangeSpeciesCount, GetExchangeSpeciesNames.

Fortran Example:

 character(len=:), allocatable :: names(:)
 status = brm%GetExchangeSpeciesNames(names)
 do i = 1, brm%GetExchangeSpeciesCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetExchangeSpeciesCount()

integer function BMIPhreeqcRM::GetExchangeSpeciesCount

(

class(bmi), intent(inout)

self

)

Returns the number of exchange species in the initial-phreeqc module. FindComponents must be called before GetExchangeSpeciesCount. This method may be useful when generating selected output definitions related to exchangers.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	number of exchange species found by call(s) to FindComponents.

See also

FindComponents, GetExchangeSpeciesNames, GetExchangeNames.

Fortran Example:

 character(len=:), allocatable :: names
 status = brm%GetExchangeSpeciesNames(names)
 do i = 1, brm%GetExchangeSpeciesCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetExchangeSpeciesNames()

integer function BMIPhreeqcRM::GetExchangeSpeciesNames	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Retrieves a list of exchange species names. The list of exchange species (such as "NaX") is derived from the list of components (FindComponents) and the list of all exchange names (such as "X") that are found by call(s) to FindComponents. FindComponents must be called before GetExchangeSpeciesNames. This method may be useful when generating selected output definitions related to exchangers.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Allocatable array of exchange species names.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetExchangeSpeciesCount, GetExchangeNames.

Fortran Example:

 character(len=:), allocatable :: names
 status = brm%GetExchangeSpeciesNames(names)
 do i = 1, brm%GetExchangeSpeciesCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetFilePrefix()

integer function BMIPhreeqcRM::GetFilePrefix	(	class(bmi), intent(inout)	self,
		character(len=:), intent(inout), allocatable	prefix
	)

Returns the reaction-module file prefix to the character argument (prefix).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
prefix	Allocatable character string where the prefix is written.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetFilePrefix.

Fortran Example:

 character(len=:), allocatable :: prefix
 status = brm%GetFilePrefix(prefix)
 

MPI:

Called by root and (or) workers.

GetGasCompMoles()

integer function BMIPhreeqcRM::GetGasCompMoles	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(inout), allocatable, target	gas_moles
	)

Transfer moles of gas components from each reaction cell to the array given in the argument list (gas_moles).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
gas_moles	Allocatable array to receive the moles of gas components for each cell. Dimension of the array is set to (nxyz, ngas_comps), where nxyz is the number of user grid cells and ngas_comps is the result of GetGasComponentsCount. If a gas component is not defined for a cell, the number of moles is set to -1. Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetGasComponentsCount, GetGasCompPressures, GetGasCompPhi, GetGasPhaseVolume, SetGasCompMoles, SetGasPhaseVolume.

Fortran Example:

 real(kind=8), allocatable :: gas_moles(:,:)
 status = brm%RunCells()
 status = brm%GetGasCompMoles(gas_moles)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetGasComponentsCount()

integer function BMIPhreeqcRM::GetGasComponentsCount

(

class(bmi), intent(inout)

self

)

Returns the number of gas phase components found by call(s) to FindComponents. FindComponents must be called before GetGasComponentsCount. This method may be useful when generating selected output definitions related to gas phases.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	number of gas phase components in the initial-phreeqc module.

See also

FindComponents, GetGasComponentsNames.

Fortran Example:

 character(len=:), allocatable :: names(:)
 status = brm%GetGasComponentsNames(names)
 do i = 1, brm%GetGasComponentsCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetGasComponentsNames()

integer function BMIPhreeqcRM::GetGasComponentsNames	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Retrieves a list of the gas component names. The list includes all gas components found by calls to FindComponents. FindComponents must be called before GetGasComponentsNames. This method may be useful when generating selected output definitions related to gas phases.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Allocatable array of gas component names.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetGasComponentsCount.

Fortran Example:

 character(len=:), allocatable :: names(:)
 status = brm%GetGasComponentsNames(names)
 do i = 1, brm%GetGasComponentsCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetGasCompPhi()

integer function BMIPhreeqcRM::GetGasCompPhi	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(inout), allocatable, target	gas_phi
	)

Transfer fugacity coefficients (phi) of gas components from each reaction cell to the array given in the argument list (gas_phi). Fugacity of a gas component is equal to the pressure of the component times the fugacity coefficient.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
gas_phi	Allocatable array to receive the fugacity coefficients of gas components for each cell. Dimension of the array is set to (nxyz, ngas_comps), where nxyz is the number of user grid cells and ngas_comps is the result of GetGasComponentsCount. If a gas component is not defined for a cell, the fugacity coefficient is set to -1. Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetGasComponentsCount, GetGasCompMoles, GetGasCompPressures, GetGasPhaseVolume, SetGasCompMoles, SetGasPhaseVolume.

Fortran Example:

 real(kind=8), allocatable :: gas_phi(:,:)
 status = brm%RunCells()
 status = brm%GetGasCompPhi(gas_phi)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetGasCompPressures()

integer function BMIPhreeqcRM::GetGasCompPressures	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(inout), allocatable, target	gas_p
	)

Transfer pressures of gas components from each reaction cell to the array given in the argument list (gas_p).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
gas_p	Allocatable array to receive the moles of gas components for each cell. Dimension of the array is set to (nxyz, ngas_comps), where nxyz is the number of user grid cells and ngas_comps is the result of GetGasComponentsCount. If a gas component is not defined for a cell, the pressure is set to -1. Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetGasComponentsCount, GetGasCompMoles, GetGasCompPhi, GetGasPhaseVolume, SetGasCompMoles, SetGasPhaseVolume.

Fortran Example:

 real(kind=8), allocatable :: gas_p(:,:)
 status = brm%RunCells()
 status = brm%GetGasCompPressures(gas_p)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetGasPhaseVolume()

integer function BMIPhreeqcRM::GetGasPhaseVolume	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable, target	gas_volume
	)

Transfer volume of gas from each reaction cell to the array given in the argument list (gas_volume).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
gas_volume	Array to receive the gas phase volumes. Dimension of the array is set to nxyz, where nxyz is the number of user grid cells (GetGridCellCount). If a gas phase is not defined for a cell, the volume is set to -1. Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetGasComponentsCount, GetGasCompMoles, GetGasCompPhi, GetGasCompPressures, SetGasCompMoles SetGasPhaseVolume.

Fortran Example:

 real(kind=8), allocatable :: gas_volume(:)
 status = brm%RunCells()
 status = brm%GetGasPhaseVolume(gas_volume)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetGfw()

integer function BMIPhreeqcRM::GetGfw	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	gfw
	)

Returns the gram formula weights (g/mol) for the components in the reaction-module component list.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
gfw	Array to receive the gram formula weights. Dimension of the array is set to ncomps, where ncomps is the number of components in the component list.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetComponents, GetComponentCount.

Fortran Example:

 character(len=:), allocatable :: components(:)
 real(kind=8), allocatable   :: gfw(:)
 ncomps = brm%FindComponents()
 status = brm%GetGfw(gfw)
 status = brm%GetComponents(components)
 do i = 1, ncomps
   write(string,"(A10, F15.4)") components(i), gfw(i)
   status = brm%OutputMessage(string)
 enddo
 

MPI:

Called by root.

GetGridCellCount()

integer function BMIPhreeqcRM::GetGridCellCount

(

class(bmi), intent(inout)

self

)

Returns the number of grid cells in the user's model, which is defined in the creation or initialization of the PhreeqcRM instance.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

Number

of grid cells in the user's model, negative is failure (See DecodeError).

See also

bmif_create, CreateMapping, InitializeYAML.

Fortran Example:

 nxyz = brm%GetGridCellCount()
 write(string1, "(A,I)") "Number of grid cells in the user's model: ", nxyz
 status = brm%OutputMessage(trim(string1))
 

MPI:

Called by root and (or) workers.

GetIPhreeqcId()

integer function BMIPhreeqcRM::GetIPhreeqcId	(	class(bmi), intent(inout)	self,
		integer, intent(in)	i
	)

Returns an IPhreeqc id for the ith IPhreeqc instance in the reaction module. For the threaded version, there are nthreads + 2 IPhreeqc instances, where nthreads is defined in the constructor (bmif_create) or initialization. The number of threads can be determined by GetThreadCount. The first nthreads (0 based) instances will be the workers, the next (nthreads) is the InitialPhreeqc instance, and the next (nthreads + 1) is the Utility instance. Getting the IPhreeqc pointer for one of these instances allows the user to use any of the IPhreeqc methods on that instance. For MPI, each process has exactly three IPhreeqc instances, one worker (number 0), one InitialPhreeqc instance (number 1), and one Utility instance (number 2).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
i	The number of the IPhreeqc instance to be retrieved (0 based).

Return values

IPhreeqc

id for the ith IPhreeqc instance, negative is failure (See DecodeError).

See also

bmif_create, GetThreadCount. See IPhreeqc documentation for descriptions of IPhreeqc methods.

Fortran Example:

 ! Utility pointer is worker number nthreads + 1
 iphreeqc_id1 = brm%GetIPhreeqcId(brm%GetThreadCount() + 1)
 

MPI:

Called by root and (or) workers.

GetIthConcentration()

integer function BMIPhreeqcRM::GetIthConcentration	(	class(bmi), intent(inout)	self,
		integer, intent(in)	i,
		real(kind=8), dimension(:), intent(inout), allocatable	c
	)

Transfer the concentration from each cell for one component to the array given in the argument list (c). The concentrations are those resulting from the last call to RunCells. Units of concentration for c are defined by SetUnitsSolution.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
i	One-based index for the component to retrieve. Indices refer to the order produced by GetComponents. The total number of components is given by GetComponentCount.
c	Allocatable array to receive the component concentrations. Dimension of the array is set to nxyz, where nxyz is the number of user grid cells (GetGridCellCount). Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetComponents, GetComponentCount, GetConcentrations.

Fortran Example:

 real(kind=8), allocatable, dimension(:) :: c
 status = brm%RunCells()
 status = brm%phreeqc_rm.GetIthConcentration(1, c)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetIthSpeciesConcentration()

integer function BMIPhreeqcRM::GetIthSpeciesConcentration	(	class(bmi), intent(inout)	self,
		integer, intent(in)	i,
		real(kind=8), dimension(:), intent(inout), allocatable	c
	)

Transfer the concentrations for one species from each cell to the array given in the argument list (c). The concentrations are those resulting from the last call to RunCells. Units of concentration for c are mol/L. To retrieve species concentrations, SetSpeciesSaveOn must be set to true. This method is for use with multicomponent diffusion calculations.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
i	One-based index for the species to retrieve. Indices refer to the order given by GetSpeciesNames. The total number of species is given by GetSpeciesCount.
c	Allocatable array to receive the species concentrations. Dimension of the array is set to nxyz, where nxyz is the number of user grid cells (GetGridCellCount). Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesCount, GetSpeciesNames, GetSpeciesConcentrations, SetSpeciesSaveOn.

Fortran Example:

 real(kind=8), allocatable, dimension(:) :: c
 status = brm%RunCells()
 status = brm%GetIthSpeciesConcentration(1, c)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetKineticReactionsCount()

integer function BMIPhreeqcRM::GetKineticReactionsCount

(

class(bmi), intent(inout)

self

)

Returns the number of kinetic reactions found by call(s) to FindComponents. FindComponents must be called before GetKineticReactionsCount. This method may be useful when generating selected output definitions related to kinetic reactions.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	number of kinetic reactions in the initial-phreeqc module.

See also

FindComponents, GetKineticReactionsNames.

Fortran Example:

 character(len=:), allocatable :: names(:)
 status = brm%GetKineticReactionsNames(names)
 do i = 1, brm%GetKineticReactionsCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetKineticReactionsNames()

integer function BMIPhreeqcRM::GetKineticReactionsNames	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Retrieves a list of kinetic reaction names. The list includes all kinetic reactions found by call(s) to FindComponents. FindComponents must be called before GetKineticReactionsNames. This method may be useful when generating selected output definitions related to kinetic reactions.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Allocatable array for kinetic reaction names

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetKineticReactionsCount.

Fortran Example:

 character(len=:), allocatable :: names(:)
 status = brm%GetKineticReactionsNames(names)
 do i = 1, brm%GetKineticReactionsCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetMpiMyself()

integer function BMIPhreeqcRM::GetMpiMyself

(

class(bmi), intent(inout)

self

)

Returns the MPI task number. For the OPENMP version, the task number is always zero and the result of GetMpiTasks is one. For the MPI version, the root task number is zero, and all workers have a task number greater than zero. The number of tasks can be obtained with GetMpiTasks. The number of tasks and computer hosts are determined at run time by the mpiexec command, and the number of reaction-module processes is defined by the communicator used in constructing the reaction modules (bmif_create).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	MPI task number for a process, negative is failure (See DecodeError).

See also

GetMpiTasks.

Fortran Example:

 write(string1, "(A,I)") "MPI task number: ", brm%GetMpiMyself()
 status = brm%OutputMessage(string1)
 

MPI:

Called by root and (or) workers.

GetMpiTasks()

integer function BMIPhreeqcRM::GetMpiTasks

(

class(bmi), intent(inout)

self

)

Returns the number of MPI processes (tasks) assigned to the reaction module. For the OPENMP version, the number of tasks is always one (although there may be multiple threads, GetThreadCount), and the task number returned by GetMpiMyself is zero. For the MPI version, the number of tasks and computer hosts are determined at run time by the mpiexec command. An MPI communicator is used in constructing reaction modules for MPI. The communicator may define a subset of the total number of MPI processes. The root task number is zero, and all workers have a task number greater than zero.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	number of MPI processes assigned to the reaction module, negative is failure (See DecodeError).

See also

GetMpiMyself, bmif_create.

Fortran Example:

 mpi_tasks = brm%GetMpiTasks()
 write(string1, "(A,I)") "Number of MPI processes: ", mpi_tasks
 status = brm%OutputMessage(string1)
 

MPI:

Called by root and (or) workers.

GetNthSelectedOutputUserNumber()

integer function BMIPhreeqcRM::GetNthSelectedOutputUserNumber	(	class(bmi), intent(inout)	self,
		integer, intent(in)	n
	)

Returns the user number for the nth selected-output definition. Definitions are sorted by user number. Phreeqc allows multiple selected-output definitions, each of which is assigned a nonnegative integer identifier by the user. The number of definitions can be obtained by GetSelectedOutputCount. To cycle through all of the definitions, GetNthSelectedOutputUserNumber can be used to identify the user number for each selected-output definition in sequence. SetCurrentSelectedOutputUserNumber is then used to select that user number for selected-output processing.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
n	The sequence number of the selected-output definition for which the user number will be returned. Fortran, 1 based.

Return values

The	user number of the nth selected-output definition, negative is failure (See DecodeError).

See also

GetCurrentSelectedOutputUserNumber, GetSelectedOutput, GetSelectedOutputColumnCount, GetSelectedOutputCount, GetSelectedOutputHeadings, GetSelectedOutputRowCount, SetCurrentSelectedOutputUserNumber, SetNthSelectedOutput, SetSelectedOutputOn.

Fortran Example:

 do isel = 1, brm%GetSelectedOutputCount()
   n_user = brm%GetNthSelectedOutputUserNumber(isel)
   status = brm%SetCurrentSelectedOutputUserNumber(n_user)
   write(*,*) "Selected output sequence number: ", isel)
   write(*,*) "Selected output user number:     ", n_user)
   col = brm%GetSelectedOutputColumnCount()
   allocate(selected_out(nxyz,col))
   status = brm%GetSelectedOutput(selected_out)
   ! Process results here
   deallocate(selected_out)
 enddo
 

MPI:

Called by root.

GetPorosity()

integer function BMIPhreeqcRM::GetPorosity	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	porosity
	)

Transfer current porosities to the array given in the argument list (porosity). Porosity is not changed by PhreeqcRM; the values are either the default values or the values set by the last call to SetPorosity.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
porosity	Array to receive the porosities. Dimension of the array is set to nxyz, where nxyz is the number of user grid cells (GetGridCellCount). Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

Fortran Example:

 real(kind=8), allocatable :: porosity(:)
 status = brm%GetPorosity(porosity)
 

MPI:

Called by root.

GetPressure()

integer function BMIPhreeqcRM::GetPressure	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	pressure
	)

Transfer current pressures to the array given in the argument list (pressure). Pressure is not usually calculated by PhreeqcRM; the values are either the default values or the values set by the last call to SetPressure. Pressures can be calculated by PhreeqcRM if a fixed-volume GAS_PHASE is used.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
pressure	Array to receive the porosities. Dimension of the array is set to nxyz, where nxyz is the number of user grid cells (GetGridCellCount). Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

Fortran Example:

 real(kind=8), allocatable :: pressure(:)
 status = brm%GetPressure(pressure)
 

MPI:

Called by root.

GetSaturation()

integer function BMIPhreeqcRM::GetSaturation	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	sat_calc
	)

This deprecated function is included for backward compatibility. Use GetSaturationCalculated.

GetSaturationCalculated()

integer function BMIPhreeqcRM::GetSaturationCalculated	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	sat_calc
	)

Returns an array of saturations (sat_calc) as calculated by the reaction module. Reactions will change the volume of solution in a cell. This method always returns solution_volume/(rv * porosity); the method SetSaturationUser has no effect on the values returned. The transport code must decide whether to ignore or account for this change in solution volume due to reactions. Following reactions, the cell saturation is calculated as solution volume (GetSolutionVolume) divided by the product of representative volume (SetRepresentativeVolume) and the porosity (SetPorosity). The cell saturation returned by GetSaturationCalculated may be less than or greater than the saturation set by the transport code (SetSaturationUser), and may be greater than or less than 1.0, even in fully saturated simulations. Only the following databases distributed with PhreeqcRM have molar volume information needed to accurately calculate solution volume and saturation: phreeqc.dat, Amm.dat, and pitzer.dat.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
sat_calc	Array to receive the saturations. Dimension of the array is set to nxyz, where nxyz is the number of user grid cells (GetGridCellCount). Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

GetSolutionVolume, SetPorosity, SetRepresentativeVolume, SetSaturationUser.

Fortran Example:

 real(kind=8), allocatable :: sat_calc(:)
 status = brm%RunCells()
 status = brm%GetSaturationCalculated(sat_calc)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetSelectedOutput()

integer function BMIPhreeqcRM::GetSelectedOutput	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(inout), allocatable	so
	)

Populates an array with values from the current selected-output definition. SetCurrentSelectedOutputUserNumber or SetNthSelectedOutput determines which of the selected-output definitions is used to populate the array.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
so	An array to contain the selected-output values. Size of the array is set to (nxyz, col), where nxyz is the number of grid cells in the user's model (GetGridCellCount), and col is the number of columns in the selected-output definition (GetSelectedOutputColumnCount).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

GetCurrentSelectedOutputUserNumber, GetNthSelectedOutputUserNumber, GetSelectedOutputColumnCount, GetSelectedOutputCount, GetSelectedOutputHeadings, GetSelectedOutputRowCount, SetCurrentSelectedOutputUserNumber, SetNthSelectedOutput, SetSelectedOutputOn.

Fortran Example:

 character(len=:), allocatable :: headings
 real(kind=8), allocatable :: selected_out
 do isel = 1, brm%GetSelectedOutputCount()
   n_user = brm%GetNthSelectedOutputUserNumber(isel)
   status = brm%SetCurrentSelectedOutputUserNumber(n_user)
   status = brm%GetSelectedOutput(selected_out)
   status = brm%GetSelectedOutputHeadings(headings)
   ! Print results
   do i = 1, brm%GetSelectedOutputRowCount()
     write(*,*) "Cell number ", i
     write(*,*) "     Selected output: "
     do j = 1, brm%GetSelectedOutputColumnCount()
       write(*,'(10x,i2,A2,A10,A2,f10.4)') j, " ", trim(headings(j)),": ", selected_out(i,j)
     enddo
   enddo
 enddo
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetSelectedOutputColumnCount()

integer function BMIPhreeqcRM::GetSelectedOutputColumnCount

(

class(bmi), intent(inout)

self

)

Returns the number of columns in the current selected-output definition. SetCurrentSelectedOutputUserNumber or SetNthSelectedOutput determines which of the selected-output definitions is used.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

Number

of columns in the current selected-output definition, negative is failure (See DecodeError).

See also

GetCurrentSelectedOutputUserNumber, GetNthSelectedOutputUserNumber, GetSelectedOutput, GetSelectedOutputCount, GetSelectedOutputHeadings, GetSelectedOutputRowCount, SetCurrentSelectedOutputUserNumber, SetNthSelectedOutput, SetSelectedOutputOn.

Fortran Example:

 real(kind=8), allocatable :: selected_out(:,:)
 do isel = 1, brm%GetSelectedOutputCount()
   n_user = brm%GetNthSelectedOutputUserNumber(isel)
   status = brm%SetCurrentSelectedOutputUserNumber(n_user)
   status = brm%GetSelectedOutput(selected_out)
   ! Process results here
 enddo
 

MPI:

Called by root.

GetSelectedOutputCount()

integer function BMIPhreeqcRM::GetSelectedOutputCount

(

class(bmi), intent(inout)

self

)

Returns the number of selected-output definitions. SetCurrentSelectedOutputUserNumber or SetNthSelectedOutput determines which of the selected-output definitions is used.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

Number

of selected-output definitions, negative is failure (See DecodeError).

See also

GetCurrentSelectedOutputUserNumber, GetNthSelectedOutputUserNumber, GetSelectedOutput, GetSelectedOutputColumnCount, GetSelectedOutputHeadings, GetSelectedOutputRowCount, SetCurrentSelectedOutputUserNumber, SetNthSelectedOutput, SetSelectedOutputOn.

Fortran Example:

 real(kind=8), allocatable :: selected_out(:,:)
 do isel = 1, brm%GetSelectedOutputCount()
   n_user = brm%GetNthSelectedOutputUserNumber(isel)
   status = brm%SetCurrentSelectedOutputUserNumber(n_user)
   status = brm%GetSelectedOutput(selected_out)
   ! Process results here
 enddo
 

MPI:

Called by root.

GetSelectedOutputHeadings()

integer function BMIPhreeqcRM::GetSelectedOutputHeadings	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	headings
	)

Returns the selected-output headings for the current selected-output file. SetCurrentSelectedOutputUserNumber or SetNthSelectedOutput determines which of the selected-output definitions is used.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
headings	Allocatable, 1D character variable. to receive the headings. Character length and dimension will be allocated as needed.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

GetCurrentSelectedOutputUserNumber, GetNthSelectedOutputUserNumber, GetSelectedOutput, GetSelectedOutputColumnCount, GetSelectedOutputCount, GetSelectedOutputRowCount, SetCurrentSelectedOutputUserNumber, SetNthSelectedOutput, SetSelectedOutputOn.

Fortran Example:

 character(len=:), allocatable, :: headings(:)
 do isel = 1, brm%GetSelectedOutputCount()
   status = brm%SetNthSelectedOutput(isel)
   status = brm%GetSelectedOutputHeadings(headings)
 enddo
 

MPI:

Called by root.

GetSelectedOutputRowCount()

integer function BMIPhreeqcRM::GetSelectedOutputRowCount

(

class(bmi), intent(inout)

self

)

Returns the number of rows in the current selected-output definition. However, the method is included only for convenience; the number of rows is always equal to the number of grid cells in the user's model, and is equal to GetGridCellCount.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

Number

of rows in the current selected-output definition, negative is failure (See DecodeError).

See also

GetCurrentSelectedOutputUserNumber, GetNthSelectedOutputUserNumber, GetSelectedOutput, GetSelectedOutputColumnCount, GetSelectedOutputCount, GetSelectedOutputHeadings, SetCurrentSelectedOutputUserNumber, SetNthSelectedOutput, SetSelectedOutputOn.

Fortran Example:

 character(len=:), allocatable :: headings
 real(kind=8), allocatable :: selected_out
 do isel = 1, brm%GetSelectedOutputCount()
   n_user = brm%GetNthSelectedOutputUserNumber(isel)
   status = brm%SetCurrentSelectedOutputUserNumber(n_user)
   status = brm%GetSelectedOutput(selected_out)
   status = brm%GetSelectedOutputHeadings(headings)
   ! Print results
   do i = 1, brm%GetSelectedOutputRowCount()
     write(*,*) "Cell number ", i
     write(*,*) "     Selected output: "
     do j = 1, brm%GetSelectedOutputColumnCount()
       write(*,'(10x,i2,A2,A10,A2,f10.4)') j, " ", trim(headings(j)),": ", selected_out(i,j)
     enddo
   enddo
 enddo
 

MPI:

Called by root.

GetSICount()

integer function BMIPhreeqcRM::GetSICount

(

class(bmi), intent(inout)

self

)

Returns the number of phases in the found by FindComponents for which saturation indices can be calculated. FindComponents must be called before GetSICount. This method may be useful when generating selected output definitions related to saturation indices.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	number of phases in the initial-phreeqc module for which saturation indices can be calculated.

See also

FindComponents, GetSINames.

Fortran Example:

 character(len=:), allocatable :: names(:)
 status = brm%GetSINames(names)
 do i = 1, brm%GetSICount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetSINames()

integer function BMIPhreeqcRM::GetSINames	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Retrieves a list of all phases for which saturation indices can be calculated. The list includes all phases that contain only elements included in the components in the initial-phreeqc module. The list assumes that all components are present to be able to calculate the entire list of SIs; it may be that one or more components are missing in any specific cell. FindComponents must be called before GetSINames. This method may be useful when generating selected output definitions related to saturation indices.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Allocatable array for saturation-index-phase names.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSICount.

Fortran Example:

 character(len=:), allocatable :: names(:)
 status = brm%GetSINames(names)
 do i = 1, brm%GetSICount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetSolidSolutionComponentsCount()

integer function BMIPhreeqcRM::GetSolidSolutionComponentsCount

(

class(bmi), intent(inout)

self

)

Returns the number of solid solution components in the initial-phreeqc module. FindComponents must be called before GetSolidSolutionComponentsCount. This method may be useful when generating selected output definitions related to solid solutions.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	number of solid solution components in the initial-phreeqc module.

See also

FindComponents, GetSolidSolutionComponentsNames, GetSolidSolutionNames.

Fortran Example:

 character(len=:), allocatable :: names(:)
 status = brm%GetSolidSolutionComponentsNames(names)
 do i = 1, brm%GetSolidSolutionComponentsCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetSolidSolutionComponentsNames()

integer function BMIPhreeqcRM::GetSolidSolutionComponentsNames	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Retrieves a list of the solid solution component names. The list includes all solid solution components found by call(s) to FindComponents. FindComponents must be called before GetSolidSolutionComponentsNames. This method may be useful when generating selected output definitions related to solid solutions.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Allocatable array for the solid solution compnent names

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSolidSolutionComponentsCount, GetSolidSolutionNames.

Fortran Example:

 character(len=:), allocatable :: names(:)
 status = brm%GetSolidSolutionComponentsNames(names)
 do i = 1, brm%GetSolidSolutionComponentsCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root.

GetSolidSolutionNames()

integer function BMIPhreeqcRM::GetSolidSolutionNames	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Retrieves a list of solid solution names. The list includes solid solution names found by call(s) to FindComponents. The solid solution names array is the same length as the solid solution components array and provides the corresponding name of solid solution containing the component. FindComponents must be called before GetSolidSolutionNames. This method may be useful when generating selected output definitions related to solid solutions.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Allocatable array for the solid solution names.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSolidSolutionComponentsCount, GetSolidSolutionComponentsNames.

Fortran Example:

 character(len=:), allocatable :: names(:), ss_names(:)
 status = brm%GetSolidSolutionComponentsNames(names)
 status = brm%GetSolidSolutionNames(names)
 do i = 1, brm%GetSolidSolutionComponentsCount()
   write(*,*) names(i), ss_names(i)
 enddo
 

MPI:

Called by root.

GetSolutionVolume()

integer function BMIPhreeqcRM::GetSolutionVolume	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	vol
	)

Transfer solution volumes from the reaction cells to the array given in the argument list (vol). Solution volumes are those calculated by the reaction module. Only the following databases distributed with PhreeqcRM have molar volume information needed to.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
vol	Allocatable array to receive the solution volumes. Dimension of the array is set to (nxyz), where nxyz is the number of user grid cells. Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

GetSaturationCalculated.

Fortran Example:

 real(kind=8), allocatable :: volume(:)allocate(volume)
 status = brm%RunCells()
 status = brm%GetSolutionVolume(volume)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetSpeciesConcentrations()

integer function BMIPhreeqcRM::GetSpeciesConcentrations	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(inout), allocatable	species_conc
	)

Transfer concentrations of aqueous species for each cell to the argument (species_conc). This method is intended for use with multicomponent-diffusion transport calculations, and SetSpeciesSaveOn must be set to true. The list of aqueous species is determined by call(s) to FindComponents and includes all aqueous species that can be made from the set of components. Solution volumes used to calculate mol/L are calculated by the reaction module. Only the following databases distributed with PhreeqcRM have molar volume information needed to accurately calculate solution volume: phreeqc.dat, Amm.dat, and pitzer.dat.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
species_conc	Allocatable array to receive the aqueous species where nxyz is the number of user grid cells (GetGridCellCount), and nspecies is the number of aqueous species (GetSpeciesCount). Concentrations are moles per liter. Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesCount, GetSpeciesD25, GetSpeciesLog10Gammas, GetSpeciesLog10Molalities, GetSpeciesNames, GetSpeciesSaveOn, GetSpeciesZ, SetSpeciesSaveOn, SpeciesConcentrations2Module.

Fortran Example:

 real(kind=8), allocatable :: species_c(:,:)
 status = brm%SetSpeciesSaveOn(1)
 ncomps = brm%FindComponents()
 status = brm%RunCells()
 status = brm%GetSpeciesConcentrations(species_c)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetSpeciesCount()

integer function BMIPhreeqcRM::GetSpeciesCount

(

class(bmi), intent(inout)

self

)

Returns the number of aqueous species in the reaction module. This method is intended for use with multicomponent-diffusion transport calculations, and SetSpeciesSaveOn must be set to true. The list of aqueous species is determined by FindComponents and includes all aqueous species that can be made from the set of components.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

IRESULT

The number of aqueous species, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesConcentrations, GetSpeciesD25, GetSpeciesLog10Gammas, GetSpeciesLog10Molalities, GetSpeciesNames, GetSpeciesSaveOn, GetSpeciesZ, SetSpeciesSaveOn, SpeciesConcentrations2Module.

Fortran Example:

 status = brm%SetSpeciesSaveOn(1)
 ncomps = FindComponents()
 status = brm%GetSpeciesCount()
 

MPI:

Called by root and (or) workers.

GetSpeciesD25()

integer function BMIPhreeqcRM::GetSpeciesD25	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	diffc
	)

Transfers diffusion coefficients at 25C to the array argument (diffc). This method is intended for use with multicomponent-diffusion transport calculations, and SetSpeciesSaveOn must be set to true. Diffusion coefficients are defined in SOLUTION_SPECIES data blocks, normally in the database file. Databases distributed with the reaction module that have diffusion coefficients defined are phreeqc.dat, Amm.dat, and pitzer.dat.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
diffc	Allocatable array to receive the diffusion coefficients at 25 C, m^2/s. Dimension of the array is set to nspecies, where nspecies is the number of aqueous species (GetSpeciesCount).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesConcentrations, GetSpeciesCount, GetSpeciesLog10Gammas, GetSpeciesLog10Molalities, GetSpeciesNames, GetSpeciesSaveOn, GetSpeciesZ, SetSpeciesSaveOn, SpeciesConcentrations2Module.

Fortran Example:

 real(kind=8), allocatable :: diffc(:)
 status = brm%SetSpeciesSaveOn(1)
 ncomps = brm%FindComponents()
 nspecies = brm%GetSpeciesD25(diffc)
 

MPI:

Called by root and (or) workers.

GetSpeciesLog10Gammas()

integer function BMIPhreeqcRM::GetSpeciesLog10Gammas	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(inout), allocatable	species_log10gammas
	)

Transfer log10 aqueous-species activity coefficients to the array argument (species_log10gammas) This method is intended for use with multicomponent-diffusion transport calculations, and SetSpeciesSaveOn must be set to true. The list of aqueous species is determined by call(s) to
FindComponents and includes all aqueous species that can be made from the set of components.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
species_log10gammas	Allocatable array to receive the log10 aqueous species activity coefficients. Dimension of the array is (nxyz, nspecies), where nxyz is the number of user grid cells (GetGridCellCount), and nspecies is the number of aqueous species (GetSpeciesCount). Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesConcentrations, GetSpeciesCount, GetSpeciesD25, GetSpeciesLog10Molalities, GetSpeciesNames, GetSpeciesSaveOn, GetSpeciesZ, SetSpeciesSaveOn, SpeciesConcentrations2Module.

Fortran Example:

 real(kind=8), allocatable :: species_log10gammas(:)
 status = brm%GetSpeciesLog10Gammas(species_log10gammas)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetSpeciesLog10Molalities()

integer function BMIPhreeqcRM::GetSpeciesLog10Molalities	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(inout), allocatable	species_log10molalities
	)

Transfer log10 aqueous-species molalities to the array argument (species_log10molalities) To use this method SetSpeciesSaveOn must be set to true. The list of aqueous species is determined by FindComponents and includes all aqueous species that can be made from the set of components.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
species_log10molalities	Array to receive the aqueous species log10 molalities. Dimension of the array is set to (nxyz, nspecies), where nxyz is the number of user grid cells (GetGridCellCount), and nspecies is the number of aqueous species (GetSpeciesCount). Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesConcentrations, GetSpeciesCount, GetSpeciesD25, GetSpeciesLog10Gammas, GetSpeciesNames, GetSpeciesSaveOn, GetSpeciesZ, SetSpeciesSaveOn, SpeciesConcentrations2Module.

Fortran Example:

 real(kind=8), allocatable :: species_log10gammas(:)
 status = brm%GetSpeciesLog10Molalities(species_log10gammas)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetSpeciesNames()

integer function BMIPhreeqcRM::GetSpeciesNames	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Provides a list of aqueous species names to the argument (names). This method is intended for use with multicomponent-diffusion transport calculations, and SetSpeciesSaveOn must be set to true. The list of aqueous species is determined by FindComponents and includes all aqueous species that can be made from the set of components.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Allocatable character array to receive the species names.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesConcentrations, GetSpeciesCount, GetSpeciesD25, GetSpeciesLog10Gammas, GetSpeciesLog10Molalities, GetSpeciesSaveOn, GetSpeciesZ, SetSpeciesSaveOn, SpeciesConcentrations2Module.

Fortran Example:

 character(len=:), allocatable :: names(:)
 status = brm%SetSpeciesSaveOn(1)
 ncomps = brm%FindComponents()
 status = brm%GetSpeciesNames(names)
 do i = 1, brm%GetSpeciesCount()
   write(*,*) names(i)
 enddo
 

MPI:

Called by root and (or) workers.

GetSpeciesSaveOn()

integer function BMIPhreeqcRM::GetSpeciesSaveOn

(

class(bmi), intent(inout)

self

)

Returns the value of the species-save property. By default, concentrations of aqueous species are not saved. Setting the species- save property to true allows aqueous species concentrations to be retrieved with GetSpeciesConcentrations, and solution compositions to be set with SpeciesConcentrations2Module.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

IRESULT

0, species are not saved; 1, species are saved; negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesConcentrations, GetSpeciesCount, GetSpeciesD25, GetSpeciesLog10Gammas, GetSpeciesLog10Molalities, GetSpeciesNames, GetSpeciesZ, SetSpeciesSaveOn, SpeciesConcentrations2Module.

Fortran Example:

 save_on = brm%GetSpeciesSaveOn()
 if (save_on .ne. 0) then
   write(*,*) "Reaction module is saving species concentrations"
 else
   write(*,*) "Reaction module is not saving species concentrations"
 end
 

MPI:

Called by root and (or) workers.

GetSpeciesZ()

integer function BMIPhreeqcRM::GetSpeciesZ	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	z
	)

Transfers the charge of each aqueous species to the array argument (z). This method is intended for use with multicomponent-diffusion transport calculations, and SetSpeciesSaveOn must be set to true.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
z	Allocatable array that receives the charge for each aqueous species. Dimension of the array is nspecies, where nspecies is is the number of aqueous species (GetSpeciesCount).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesConcentrations, GetSpeciesCount, GetSpeciesD25, GetSpeciesLog10Gammas, GetSpeciesLog10Molalities, GetSpeciesNames, GetSpeciesSaveOn, SetSpeciesSaveOn, SpeciesConcentrations2Module.

Fortran Example:

 real(kind=8), allocatable :: z(:)
 status = brm%SetSpeciesSaveOn(1)
 ncomps = brm%FindComponents()
 nspecies = brm%GetSpeciesCount()
 status = brm%GetSpeciesZ(z)
 

MPI:

Called by root and (or) workers.

GetStartCell()

integer function BMIPhreeqcRM::GetStartCell	(	class(bmi), intent(inout)	self,
		integer, dimension(:), intent(inout), allocatable	sc
	)

Returns an array with the starting cell numbers from the range of cell numbers assigned to each worker.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
sc	Allocatable array to receive the starting cell numbers. Dimension of the array is the number of threads (OpenMP) or the number of processes (MPI).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

bmif_create, GetEndCell, GetMpiTasks, GetThreadCount.

Fortran Example:

 integer, allocatable :: sc(:)
 status = brm%GetStartCell(sc)
 

MPI:

Called by root and (or) workers.

GetSurfaceNames()

integer function BMIPhreeqcRM::GetSurfaceNames	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Retrieves the surface names (such as "Hfo") that corresponds with the surface species names. The lists of surface species names and surface names are the same length. FindComponents must be called before GetSurfaceNames. This method may be useful when generating selected output definitions related to surfaces.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Allocatable array for the surface names.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSurfaceSpeciesCount, GetSurfaceSpeciesNames, GetSurfaceTypes.

Fortran Example:

 character(len=:), allocatable :: surface_species_names(:), types(:), surface_names(:)
 status = brm%GetSurfaceSpeciesNames(surface_species_names)
 status = brm%GetSurfaceTypes(types)
 status = brm%GetSurfaceNames(surface_names)
 do i = 1, brm%GetSurfaceSpeciesCount()
   write(*,*) surface_species_names(i), types(i), surface_names(i)
 enddo
 

MPI:

Called by root.

GetSurfaceSpeciesCount()

integer function BMIPhreeqcRM::GetSurfaceSpeciesCount

(

class(bmi), intent(inout)

self

)

Returns the number of surface species (such as "Hfo_wOH") found by call(s) to FindComponents. FindComponents must be called before GetSurfaceSpeciesCount. This method may be useful when generating selected output definitions related to surfaces.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	number of surface species in the reaction module.

See also

FindComponents, GetSurfaceSpeciesNames, GetSurfaceTypes, GetSurfaceNames.

Fortran Example:

 character(len=:), allocatable :: surface_species_names(:), types(:), surface_names(:)
 status = brm%GetSurfaceSpeciesNames(surface_species_names)
 status = brm%GetSurfaceTypes(types)
 status = brm%GetSurfaceNames(surface_names)
 do i = 1, brm%GetSurfaceSpeciesCount()
   write(*,*) surface_species_names(i), types(i), surface_names(i)
 enddo
 

MPI:

Called by root.

GetSurfaceSpeciesNames()

integer function BMIPhreeqcRM::GetSurfaceSpeciesNames	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Retrieves a list of surface species names. The list of surface species (for example, "Hfo_wOH") is derived from the list of components (FindComponents) and the list of all surface types (such as "Hfo_w") that are found by call(s) to FindComponents. FindComponents must be called before GetSurfaceSpeciesNames. This method may be useful when generating selected output definitions related to surfaces.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Allocatable array to receive the surface species names. Dimension of the array is set to nspecies, where nspecies is returned by GetSpeciesCount.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSurfaceSpeciesCount, GetSurfaceTypes, GetSurfaceNames.

Fortran Example:

 character(len=:), allocatable :: surface_species_names(:), types(:), surface_names(:)
 status = brm%GetSurfaceSpeciesNames(surface_species_names)
 status = brm%GetSurfaceTypes(types)
 status = brm%GetSurfaceNames(surface_names)
 do i = 1, brm%GetSurfaceSpeciesCount()
   write(*,*) surface_species_names(i), types(i), surface_names(i)
 enddo
 

MPI:

Called by root.

GetSurfaceTypes()

integer function BMIPhreeqcRM::GetSurfaceTypes	(	class(bmi), intent(inout)	self,
		character(len=:), dimension(:), intent(inout), allocatable	names
	)

Retrieves the surface site types (such as "Hfo_w") that correspond with the surface species names. The lists of surface species names and surface species types are the same length. FindComponents must be called before GetSurfaceTypes. This method may be useful when generating selected output definitions related to surfaces.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
names	Allocatable array to receive surface types.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSurfaceSpeciesCount, GetSurfaceSpeciesNames, GetSurfaceNames.

Fortran Example:

 character(len=:), allocatable :: surface_species_names(:), types(:), surface_names(:)
 status = brm%GetSurfaceSpeciesNames(surface_species_names)
 status = brm%GetSurfaceTypes(types)
 status = brm%GetSurfaceNames(surface_names)
 do i = 1, brm%GetSurfaceSpeciesCount()
   write(*,*) surface_species_names(i), types(i), surface_names(i)
 enddo
 

MPI:

Called by root.

GetTemperature()

integer function BMIPhreeqcRM::GetTemperature	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	temperature
	)

Returns an array of temperatures (temperature) from the reaction module. Reactions do not change the temperature, so the temperatures are either the temperatures at initialization, or the values set with the last call to SetTemperature.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
temperature	Allocatable array to receive the temperatures. Dimension of the array is set to nxyz, where nxyz is the number of user grid cells (GetGridCellCount). Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetTemperature.

Fortran Example:

 real(kind=8), allocatable :: temperature(:)
 status = brm%GetTemperature(temperature)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

GetThreadCount()

integer function BMIPhreeqcRM::GetThreadCount

(

class(bmi), intent(inout)

self

)

Returns the number of threads, which is equal to the number of workers used to run in parallel with OPENMP. For the OPENMP version, the number of threads is set implicitly or explicitly with bmif_create. For the MPI version, the number of threads is always one for each process.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

Number

of threads, negative is failure (See DecodeError).

See also

GetMpiTasks.

Fortran Example:

 write(string1, "(A,I)") "Number of threads: ", brm%GetThreadCount()
 status = brm%OutputMessage(string1)
 

MPI:

Called by root and (or) workers; result is always 1.

GetTime()

real(kind=8) function BMIPhreeqcRM::GetTime

(

class(bmi), intent(inout)

self

)

Returns the current simulation time in seconds. The reaction module does not change the time value, so the returned value is equal to the default (0.0) or the last time set by SetTime.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	current simulation time in seconds.

See also

GetTimeconversion, GetTimestep, SetTime, SetTimeConversion, SetTimeStep.

Fortran Example:

 write(string, "(A32,F15.1,A)") "Beginning transport calculation ", &
       brm%GetTime() * brm%GetTimeconversion(), " days"
 status = brm%LogMessage(string)
 

MPI:

Called by root and (or) workers.

GetTimeconversion()

real(kind=8) function BMIPhreeqcRM::GetTimeconversion

(

class(bmi), intent(inout)

self

)

Returns a multiplier to convert time from seconds to another unit, as specified by the user. The reaction module uses seconds as the time unit. The user can set a conversion factor (SetTimeConversion) and retrieve it with GetTimeconversion. The reaction module only uses the conversion factor when printing the long version of cell chemistry (SetPrintChemistryOn), which is rare. Default conversion factor is 1.0.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

Multiplier

to convert seconds to another time unit.

See also

GetTime, GetTimestep, SetTime, SetTimeConversion, SetTimeStep.

Fortran Example:

 write(string, "(A32,F15.1,A)") "Beginning transport calculation ", &
       brm%GetTime() * brm%GetTimeconversion(), " days"
 status = brm%LogMessage(string)
 

MPI:

Called by root and (or) workers.

GetTimestep()

real(kind=8) function BMIPhreeqcRM::GetTimestep

(

class(bmi), intent(inout)

self

)

Returns the current simulation time step in seconds. This is the time over which kinetic reactions are integrated in a call to RunCells. The reaction module does not change the time step value, so the returned value is equal to the default (0.0) or the last time step set by SetTimeStep.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

The	current simulation time step in seconds.

See also

GetTime, GetTimeconversion, SetTime, SetTimeConversion, SetTimeStep.

Fortran Example:

 write(string, "(A32,F15.1,A)") "          Time step             ", &
       brm%GetTimestep() * brm%GetTimeconversion(), " days"
 status = brm%LogMessage(string)
 

MPI:

Called by root and (or) workers.

GetViscosity()

integer function BMIPhreeqcRM::GetViscosity	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(inout), allocatable	viscosity
	)

Transfer current viscosities to the array given in the argument list (viscosity).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
viscosity	Allocatable array to receive the viscosities. Dimension of the array is nxyz, where nxyz is the number of user grid cells (GetGridCellCount). Values for inactive cells are set to 1e30.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

Fortran Example:

 real(kind=8), allocatable :: viscosity(:)
 status = brm%GetViscosity(viscosity)
 

MPI:

Called by root.

InitialEquilibriumPhases2Module()

integer function BMIPhreeqcRM::InitialEquilibriumPhases2Module	(	class(bmi), intent(inout)	self,
		integer, dimension(:), intent(in)	equilibrium_phases
	)

Transfer EQUILIBRIUM_PHASES definitions from the InitialPhreeqc instance to the reaction-module workers. equilibrium_phases is used to select EQUILIBRIUM_PHASES definitions for each cell of the model. equilibrium_phases is dimensioned nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
equilibrium_phases	Array of EQUILIBRIUM_PHASES index numbers that refer to definitions in the InitialPhreeqc instance. Size is nxyz. Negative values are ignored, resulting in no transfer of an EQUILIBRIUM_PHASES definition for that cell. (Note that an EQUILIBRIUM_PHASES definition for a cell could be defined by other calls to InitialEquilibriumPhases2Module, InitialPhreeqc2Module, or InitialPhreeqcCell2Module.)

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialSolutions2Module, InitialExchanges2Module, InitialGasPhases2Module, InitialKinetics2Module, InitialSolidSolutions2Module, InitialSurfaces2Module, InitialPhreeqc2Module, InitialPhreeqcCell2Module.

Fortran Example:

 allocate(equilibrium_phases(nxyz))
 equilibrium_phases = 1
 status = brm%InitialEquilibriumPhases2Module(equilibrium_phases);
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

InitialExchanges2Module()

integer function BMIPhreeqcRM::InitialExchanges2Module	(	class(bmi), intent(inout)	self,
		integer, dimension(:), intent(in)	exchanges
	)

Transfer EXCHANGE definitions from the InitialPhreeqc instance to the reaction-module workers. exchanges is used to select EXCHANGE definitions for each cell of the model. exchanges is dimensioned nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
exchanges	Vector of EXCHANGE index numbers that refer to definitions in the InitialPhreeqc instance. Size is nxyz. Negative values are ignored, resulting in no transfer of an EXCHANGE definition for that cell. (Note that an EXCHANGE definition for a cell could be defined by other calls to InitialExchanges2Module, InitialPhreeqc2Module, or InitialPhreeqcCell2Module.)

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialSolutions2Module, InitialEquilibriumPhases2Module, InitialGasPhases2Module, InitialKinetics2Module, InitialSolidSolutions2Module, InitialSurfaces2Module, InitialPhreeqc2Module, InitialPhreeqcCell2Module.

Fortran Example:

 allocate(exchanges(nxyz))
 exchanges = 1
 status = brm%InitialExchanges2Module(exchanges);
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

InitialGasPhases2Module()

integer function BMIPhreeqcRM::InitialGasPhases2Module	(	class(bmi), intent(inout)	self,
		integer, dimension(:), intent(in)	gas_phases
	)

Transfer GAS_PHASE definitions from the InitialPhreeqc instance to the reaction-module workers. gas_phases is used to select GAS_PHASE definitions for each cell of the model. gas_phases is dimensioned nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
gas_phases	Vector of GAS_PHASE index numbers that refer to definitions in the InitialPhreeqc instance.Size is nxyz. Negative values are ignored, resulting in no transfer of a GAS_PHASE definition for that cell. (Note that an GAS_PHASE definition for a cell could be defined by other calls to InitialGasPhases2Module, InitialPhreeqc2Module, or InitialPhreeqcCell2Module.)

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialSolutions2Module, InitialEquilibriumPhases2Module, InitialExchanges2Module, InitialKinetics2Module, InitialSolidSolutions2Module, InitialSurfaces2Module, InitialPhreeqc2Module, InitialPhreeqcCell2Module.

Fortran Example:

 allocate(gas_phases(nxyz))
 gas_phases = 1
 status = brm%InitialGasPhases2Module(gas_phases);
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

InitializeYAML()

integer function BMIPhreeqcRM::InitializeYAML	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	yaml_name
	)

A YAML file can be used to initialize an instance of PhreeqcRM.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
yaml_name	String containing the YAML file name.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

The file contains a YAML map of PhreeqcRM methods and the arguments corresponding to the methods. Note that the PhreeqcRM methods do not have the "" prefix and the id argument is not included. For example,

 LoadDatabase: phreeqc.dat
 RunFile:
 workers: true
 initial_phreeqc: true
 utility: true
 chemistry_name: advect.pqi
 

InitializeYAML will read the YAML file and execute the specified methods with the specified arguments. Using YAML terminology, the argument(s) for a method may be a scalar, a sequence, or a map, depending if the argument is a single item, a single vector, or there are multiple arguments. In the case of a map, the name associated with each argument (for example "chemistry_name" above) is arbitrary. The names of the map keys for map arguments are not used in parsing the YAML file; only the order of the arguments is important.

The following list gives the PhreeqcRM methods that can be specified in a YAML file and the arguments that are required. The arguments are described with C++ formats, which are sufficient to identify which arguments are YAML scalars (single bool/logical, int, double, string/character argument), sequences (single vector argument), or maps (multiple arguments).

 CloseFiles(void);
 CreateMapping(std::vector< int >& grid2chem);
 DumpModule();
 FindComponents();
 InitialEquilibriumPhases2Module(std::vector< int > equilibrium_phases);
 InitialExchanges2Module(std::vector< int > exchanges);
 InitialGasPhases2Module(std::vector< int > gas_phases);
 InitialKineticss2Module(std::vector< int > kinetics);
 InitialSolidSolutions2Module(std::vector< int > solid_solutions);
 InitialSolutions2Module(std::vector< int > solutions);
 InitialSurfaces2Module(std::vector< int > surfaces);
 InitialPhreeqc2Module(std::vector< int > initial_conditions1);
 InitialPhreeqc2Module(std::vector< int > initial_conditions1, std::vector< int > initial_conditions2, std::vector< double > fraction1);
 InitialPhreeqcCell2Module(int n, std::vector< int > cell_numbers);
 LoadDatabase(std::string database);
 OpenFiles(void);
 OutputMessage(std::string str);
 RunCells(void);
 RunFile(bool workers, bool initial_phreeqc, bool utility, std::string chemistry_name);
 RunString(bool workers, bool initial_phreeqc, bool utility, std::string input_string);
 ScreenMessage(std::string str);
 SetComponentH2O(bool tf);
 SetConcentrations(std::vector< double > c);
 SetCurrentSelectedOutputUserNumber(int n_user);
 SetDensityUser(std::vector< double > density);
 SetDumpFileName(std::string dump_name);
 SetErrorHandlerMode(int mode);
 SetErrorOn(bool tf);
 SetFilePrefix(std::string prefix);
 SetGasCompMoles(std::vector< double > gas_moles);
 SetGasPhaseVolume(std::vector< double > gas_volume);
 SetPartitionUZSolids(bool tf);
 SetPorosity(std::vector< double > por);
 SetPressure(std::vector< double > p);
 SetPrintChemistryMask(std::vector< int > cell_mask);
 SetPrintChemistryOn(bool workers, bool initial_phreeqc, bool utility);
 SetRebalanceByCell(bool tf);
 SetRebalanceFraction(double f);
 SetRepresentativeVolume(std::vector< double > rv);
 SetSaturationUser(std::vector< double > sat);
 SetScreenOn(bool tf);
 SetSelectedOutputOn(bool tf);
 SetSpeciesSaveOn(bool save_on);
 SetTemperature(std::vector< double > t);
 SetTime(double time);
 SetTimeConversion(double conv_factor);
 SetTimeStep(double time_step);
 SetUnitsExchange(int option);
 SetUnitsGasPhase(int option);
 SetUnitsKinetics(int option);
 SetUnitsPPassemblage(int option);
 SetUnitsSolution(int option);
 SetUnitsSSassemblage(int option);
 SetUnitsSurface(int option);
 SpeciesConcentrations2Module(std::vector< double > species_conc);
 StateSave(int istate);
 StateApply(int istate);
 StateDelete(int istate);
 UseSolutionDensityVolume(bool tf);
 WarningMessage(std::string warnstr);
 

Fortran Example:

 id = Create(nxyz, MPI_COMM_WORLD)
 status = brm%InitializeYAML("myfile.yaml")
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

InitialKinetics2Module()

integer function BMIPhreeqcRM::InitialKinetics2Module	(	class(bmi), intent(inout)	self,
		integer, dimension(:), intent(in)	kinetics
	)

Transfer KINETICS definitions from the InitialPhreeqc instance to the reaction-module workers. kinetics is used to select KINETICS definitions for each cell of the model. kinetics is dimensioned nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
kinetics	Array of KINETICS index numbers that refer to definitions in the InitialPhreeqc instance. Size is nxyz. Negative values are ignored, resulting in no transfer of a KINETICS definition for that cell. (Note that an KINETICS definition for a cell could be defined by other calls to InitialKinetics2Module, InitialPhreeqc2Module, or InitialPhreeqcCell2Module.)

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialSolutions2Module, InitialEquilibriumPhases2Module, InitialExchanges2Module, InitialGasPhases2Module, InitialSolidSolutions2Module, InitialSurfaces2Module, InitialPhreeqc2Module, InitialPhreeqcCell2Module.

Fortran Example:

 allocate(kinetics(nxyz))
 kinetics = 1
 status = brm%InitialKinetics2Module(kinetics);
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

InitialPhreeqc2Concentrations()

integer function BMIPhreeqcRM::InitialPhreeqc2Concentrations	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(inout), allocatable	bc_conc,
		integer, intent(in)	n_boundary,
		integer, dimension(:), intent(in)	bc1,
		integer, dimension(:), intent(in), optional	bc2,
		real(kind=8), dimension(:), intent(in), optional	f1
	)

Fills an array (bc_conc) with concentrations from solutions in the InitialPhreeqc instance. The method is used to obtain concentrations for boundary conditions. If a negative value is used for a cell in bc1, then the highest numbered solution in the InitialPhreeqc instance will be used for that cell. Concentrations may be a mixture of two solutions, bc1 and bc2, with a mixing fraction for bc1 1 of f1 and mixing fraction for bc2 of (1 - f1). A negative value for bc2 implies no mixing, and the associated value for f1 is ignored. If bc2 and f1 are omitted, no mixing is used; concentrations are derived from bc1 only.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
bc_conc	Allocatable array of concentrations extracted from the InitialPhreeqc instance. The dimension of bc_conc is set to (n_boundary, ncomp), where ncomp is the number of components returned from FindComponents or GetComponentCount.
n_boundary	The number of boundary condition solutions that need to be filled.
bc1	Array of solution index numbers that refer to solutions in the InitialPhreeqc instance. Size is n_boundary.
bc2	Array of solution index numbers that that refer to solutions in the InitialPhreeqc instance and are defined to mix with bc1. Size is n_boundary. This argument and f1 are optional.
f1	Array with fraction of bc1 that mixes with (1-f1) of bc2.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetComponentCount.

Fortran Example:

 real(kind=8), allocatable :: bc_conc(:,:)
 integer, allocatable :: bc1(:), bc2(:)
 real(kind=8), allocatable :: f1(:)
 nbound = 1
 allocate(bc1(nbound), bc2(nbound), f1(nbound))
 bc1 = 0           ! solution 0 from InitialPhreeqc instance
 bc2 = -1          ! no bc2 solution for mixing
 f1 = 1.0          ! mixing fraction for bc1
 status = brm%InitialPhreeqc2Concentrations(bc_conc, nbound, bc1, bc2, f1)
 

MPI:

Called by root.

InitialPhreeqc2Module()

integer function BMIPhreeqcRM::InitialPhreeqc2Module	(	class(bmi), intent(inout)	self,
		integer, dimension(:,:), intent(inout)	ic1,
		integer, dimension(:,:), intent(in), optional	ic2,
		real(kind=8), dimension(:,:), intent(inout), optional	f1
	)

Transfer solutions and reactants from the InitialPhreeqc instance to the reaction-module workers, possibly with mixing. In its simplest form, ic1 is used to select initial conditions, including solutions and reactants, for each cell of the model, without mixing. ic1 is dimensioned (nxyz, 7), where nxyz is the number of grid cells in the user's model (GetGridCellCount). The dimension of 7 refers to solutions and reactants in the following order: (1) SOLUTIONS, (2) EQUILIBRIUM_PHASES, (3) EXCHANGE, (4) SURFACE, (5) GAS_PHASE, (6) SOLID_SOLUTIONS, and (7) KINETICS. In Fortran, ic1(100, 4) = 2, indicates that cell 99 (0 based) contains the SURFACE definition with user number 2 that has been defined in the InitialPhreeqc instance (either by RunFile or RunString).

It is also possible to mix solutions and reactants to obtain the initial conditions for cells. For mixing, ic2 contains numbers for a second entity that mixes with the entity defined in ic1. F1 contains the mixing fraction for ic1, whereas (1 - f1) is the mixing fraction for ic2. In Fortran, ic1(100, 4) = 2, initial_conditions2(100, 4) = 3, f1(100, 4) = 0.25 indicates that cell 99 (0 based) contains a mixture of 0.25 SURFACE 2 and 0.75 SURFACE 3, where the surface compositions have been defined in the InitialPhreeqc instance. If the user number in ic2 is negative, no mixing occurs. If ic2 and f1 are omitted, no mixing is used, and initial conditions are derived solely from ic1.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
ic1	Array of solution and reactant index numbers that refer to definitions in the InitialPhreeqc instance. Size is (nxyz,7). The order of definitions is given above. Negative values are ignored, resulting in no definition of that entity for that cell.
ic2	Array of solution and reactant index numbers that refer to definitions in the InitialPhreeqc instance. Nonnegative values of ic2 result in mixing with the entities defined in ic1. Negative values result in no mixing. Size is (nxyz,7). The order of definitions is given above. Optional in Fortran; omitting results in no mixing.
f1	Fraction of ic1 that mixes with (1-f1) of ic2. Size is (nxyz,7). The order of definitions is given above. Optional in Fortran; omitting results in no mixing.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialSolutions2Module, InitialEquilibriumPhases2Module, InitialExchanges2Module, InitialGasPhases2Module, InitialKinetics2Module, InitialSolidSolutions2Module, InitialSurfaces2Module, InitialPhreeqcCell2Module.

Fortran Example:

 allocate(ic1(nxyz,7), ic2(nxyz,7), f1(nxyz,7))
 ic1 = -1
 ic2 = -1
 f1 = 1.0
 do i = 1, nxyz
   ic1(i,1) = 1       ! Solution 1
   ic1(i,2) = -1      ! Equilibrium phases none
   ic1(i,3) = 1       ! Exchange 1
   ic1(i,4) = -1      ! Surface none
   ic1(i,5) = -1      ! Gas phase none
   ic1(i,6) = -1      ! Solid solutions none
   ic1(i,7) = -1      ! Kinetics none
 enddo
 status = brm%InitialPhreeqc2Module(ic1, ic2, f1)1))
 ! No mixing is defined, so the following is equivalent
 status = brm%InitialPhreeqc2Module(ic1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

InitialPhreeqc2SpeciesConcentrations()

integer function BMIPhreeqcRM::InitialPhreeqc2SpeciesConcentrations	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(inout), allocatable	bc_conc,
		integer, intent(in)	n_boundary,
		integer, dimension(:), intent(in)	bc1,
		integer, dimension(:), intent(in), optional	bc2,
		real(kind=8), dimension(:), intent(in), optional	f1
	)

Fills an array (bc_conc) with aqueous species concentrations from solutions in the InitialPhreeqc instance. This method is intended for use with multicomponent-diffusion transport calculations, and SetSpeciesSaveOn must be set to true. The method is used to obtain aqueous species concentrations for boundary conditions. If a negative value is used for a cell in bc1, then the highest numbered solution in the InitialPhreeqc instance will be used for that cell. Concentrations may be a mixture of two solutions, bc1 and bc2, with a mixing fraction for bc1 of f1 and mixing fraction for bc2 of (1 - f1). A negative value for bc2 implies no mixing, and the associated value for f1 is ignored. If bc2 and f1 are omitted, no mixing is used; concentrations are derived from bc1 only.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
bc_conc	Array of aqueous concentrations extracted from the InitialPhreeqc instance. The dimension of species_c is set to (n_boundary, nspecies), where nspecies is the number of aqueous species returned from GetSpeciesCount.
n_boundary	The number of boundary condition solutions that need to be filled.
bc1	Array of solution index numbers that refer to solutions in the InitialPhreeqc instance. Size is n_boundary.
bc2	Array of solution index numbers that that refer to solutions in the InitialPhreeqc instance and are defined to mix with bc1. Size is n_boundary. Optional in Fortran.
f1	Fraction of bc1 that mixes with (1-f1) of bc2. Size is n_boundary. Optional in Fortran.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesCount, SetSpeciesSaveOn.

Fortran Example:

 real(kind=8), allocatable :: bc_conc(:,:)
 nbound = 1
 allocate(bc1(nbound), bc2(nbound), f1(nbound))
 bc1 = 0           ! solution 0 from InitialPhreeqc instance
 bc2 = -1          ! no bc2 solution for mixing
 f1 = 1.0          ! mixing fraction for bc1
 status = brm%InitialPhreeqc2SpeciesConcentrations(bc_conc, nbound, bc1, bc2, f1)
 

MPI:

Called by root.

InitialPhreeqcCell2Module()

integer function BMIPhreeqcRM::InitialPhreeqcCell2Module	(	class(bmi), intent(inout)	self,
		integer, intent(in)	n_user,
		integer, dimension(:), intent(in)	cell_numbers,
		integer, intent(in)	n_cell
	)

A cell numbered n_user in the InitialPhreeqc instance is selected to populate a series of cells. All reactants with the number n_user are transferred along with the solution. If MIX n_user exists, it is used for the definition of the solution. If n_user is negative, n_user is redefined to be the largest solution or MIX number in the InitialPhreeqc instance. All reactants for each cell in the list cell_numbers are removed before the cell definition is copied from the InitialPhreeqc instance to the workers.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
n_user	Cell number refers to a solution or MIX and associated reactants in the InitialPhreeqc instance. A negative number indicates the largest solution or MIX number in the InitialPhreeqc instance will be used.
cell_numbers	A list of cell numbers in the user's grid-cell numbering system that will be populated with cell n_user from the InitialPhreeqc instance.
n_cell	The number of cell numbers in the cell_numbers list.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialPhreeqc2Module.

Fortran Example:

 allocate (cell_numbers(2))
 cell_numbers(1) = 18
 cell_numbers(2) = 19
 ! n will be the largest SOLUTION number in InitialPhreeqc instance
 ! copies solution and reactants to cells 18 and 19
 status = brm%InitialPhreeqcCell2Module(-1, cell_numbers, 2)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

InitialSolidSolutions2Module()

integer function BMIPhreeqcRM::InitialSolidSolutions2Module	(	class(bmi), intent(inout)	self,
		integer, dimension(:), intent(in)	solid_solutions
	)

Transfer SOLID_SOLUTIONS definitions from the InitialPhreeqc instance to the reaction-module workers. solid_solutions is used to select SOLID_SOLUTIONS definitions for each cell of the model. solid_solutions is dimensioned nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
solid_solutions	Array of SOLID_SOLUTIONS index numbers that refer to definitions in the InitialPhreeqc instance. Size is nxyz. Negative values are ignored, resulting in no transfer of a SOLID_SOLUTIONS definition for that cell. (Note that an SOLID_SOLUTIONS definition for a cell could be defined by other calls to InitialSolidSolutions2Module, InitialPhreeqc2Module, or InitialPhreeqcCell2Module.)

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialSolutions2Module, InitialEquilibriumPhases2Module, InitialExchanges2Module, InitialGasPhases2Module, InitialKinetics2Module, InitialSurfaces2Module, InitialPhreeqc2Module, InitialPhreeqcCell2Module.

Fortran Example:

 allocate(solid_solutions(nxyz))
 solid_solutions = 1
 status = brm%InitialSolidSolutions2Module(solid_solutions);
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

InitialSolutions2Module()

integer function BMIPhreeqcRM::InitialSolutions2Module	(	class(bmi), intent(inout)	self,
		integer, dimension(:), intent(in)	solutions
	)

Transfer SOLUTION definitions from the InitialPhreeqc instance to the reaction- module workers. solutions is used to select SOLUTION definitions for each cell of the model. solutions is dimensioned nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
solutions	Array of SOLUTION index numbers that refer to definitions in the InitialPhreeqc instance. Size is nxyz. Negative values are ignored, resulting in no transfer of a SOLUTION definition for that cell. (Note that all cells must have a SOLUTION definition, which could be defined by other calls to InitialSolutions2Module, InitialPhreeqc2Module, or InitialPhreeqcCell2Module.)

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialEquilibriumPhases2Module, InitialExchanges2Module, InitialGasPhases2Module, InitialKinetics2Module, InitialSolidSolutions2Module, InitialSurfaces2Module, InitialPhreeqc2Module, InitialPhreeqcCell2Module.

Fortran Example:

 allocate(solutions(nxyz))
 solutions = 1
 status = brm%InitialSolutions2Module(solutions);
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

InitialSurfaces2Module()

integer function BMIPhreeqcRM::InitialSurfaces2Module	(	class(bmi), intent(inout)	self,
		integer, dimension(:), intent(in)	surfaces
	)

Transfer SURFACE definitions from the InitialPhreeqc instance to the reaction-module workers. surfaces is used to select SURFACE definitions for each cell of the model. surfaces is dimensioned nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
surfaces	Array of SURFACE index numbers that refer to definitions in the InitialPhreeqc instance. Size is nxyz. Negative values are ignored, resulting in no transfer of a SURFACE definition for that cell. (Note that an SURFACE definition for a cell could be defined by other calls to InitialSurfaces2Module, InitialPhreeqc2Module, or InitialPhreeqcCell2Module.)

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialSolutions2Module, InitialEquilibriumPhases2Module, InitialExchanges2Module, InitialGasPhases2Module, InitialKinetics2Module, InitialSolidSolutions2Module, InitialPhreeqc2Module, InitialPhreeqcCell2Module.

Fortran Example:

 allocate(surfaces(nxyz))
 surfaces = 1
 status = brm%InitialSurfaces2Module(surfaces);
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

LoadDatabase()

integer function BMIPhreeqcRM::LoadDatabase	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	db_name
	)

Load a database for all IPhreeqc instances–workers, InitialPhreeqc, and Utility. All definitions of the reaction module are cleared (SOLUTION_SPECIES, PHASES, SOLUTIONs, etc.), and the database is read.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
db_name	String containing the database name.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

bmif_create.

Fortran Example:

 status = brm%LoadDatabase("phreeqc.dat")
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

LogMessage()

integer function BMIPhreeqcRM::LogMessage	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	str
	)

Print a message to the log file.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
str	String to be printed.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

ErrorMessage, OpenFiles, OutputMessage, ScreenMessage, WarningMessage.

Fortran Example:

 write(string, "(A32,F15.1,A)") "Beginning transport calculation ", &
       brm%GetTime() * brm%GetTimeconversion(), " days"
 status = brm%LogMessage(string)
 

MPI:

Called by root.

MpiWorker()

integer function BMIPhreeqcRM::MpiWorker

(

class(bmi), intent(inout)

self

)

MPI only. Workers (processes with GetMpiMyself > 0) must call MpiWorker to be able to respond to messages from the root to accept data, perform calculations, and (or) return data. MpiWorker contains a loop that reads a message from root, performs a task, and waits for another message from root. SetConcentrations, RunCells, and GetConcentrations are examples of methods that send a message from root to get the workers to perform a task. The workers will respond to all methods that are designated "workers must be in the loop of MpiWorker" in the MPI section of the method documentation. The workers will continue to respond to messages from root until root calls MpiWorkerBreak.

(Advanced) The list of tasks that the workers perform can be extended by using SetMpiWorkerCallback. It is then possible to use the MPI processes to perform other developer-defined tasks, such as transport calculations, without exiting from the MpiWorker loop. Alternatively, root calls MpiWorkerBreak to allow the workers to continue past a call to MpiWorker. The workers perform developer-defined calculations, and then MpiWorker is called again to respond to requests from root to perform reaction-module tasks.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

IRESULT

0 is success, negative is failure (See DecodeError). MpiWorker returns a value only when MpiWorkerBreak is called by root.

See also

MpiWorkerBreak, SetMpiWorkerCallback.

Fortran Example:

 status = brm%MpiWorker()
 

MPI:

Called by all workers.

MpiWorkerBreak()

integer function BMIPhreeqcRM::MpiWorkerBreak

(

class(bmi), intent(inout)

self

)

MPI only. This method is called by root to force workers (processes with GetMpiMyself > 0) to return from a call to MpiWorker. MpiWorker contains a loop that reads a message from root, performs a task, and waits for another message from root. The workers respond to all methods that are designated "workers must be in the loop of MpiWorker" in the MPI section of the method documentation. The workers will continue to respond to messages from root until root calls MpiWorkerBreak.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

MpiWorker, SetMpiWorkerCallback.

Fortran Example:

 status = brm%MpiWorkerBreak()
 

MPI:

Called by root.

OpenFiles()

integer function BMIPhreeqcRM::OpenFiles

(

class(bmi), intent(inout)

self

)

Opens the output and log files. Files are named prefix.chem.txt and prefix.log.txt based on the prefix defined by SetFilePrefix.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

CloseFiles, ErrorMessage, GetFilePrefix, LogMessage, OutputMessage, SetFilePrefix, WarningMessage.

Fortran Example:

 status = brm%SetFilePrefix("Advect_f90")
 status = brm%OpenFiles()
 

MPI:

Called by root.

OutputMessage()

integer function BMIPhreeqcRM::OutputMessage	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	str
	)

Print a message to the output file.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
str	String to be printed.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

ErrorMessage, LogMessage, ScreenMessage, WarningMessage.

Fortran Example:

 write(string1, "(A,I10)") "Number of threads:                                ", brm%GetThreadCount()
 status = brm%OutputMessage(string1)
 write(string1, "(A,I10)") "Number of MPI processes:                          ", brm%GetMpiTasks()
 status = brm%OutputMessage(string1)
 write(string1, "(A,I10)") "MPI task number:                                  ", brm%GetMpiMyself()
 status = brm%OutputMessage(string1)
 status = brm%GetFilePrefix(string)
 write(string1, "(A,A)") "File prefix:                                        ", string
 status = brm%OutputMessage(trim(string1))
 write(string1, "(A,I10)") "Number of grid cells in the user's model:         ", brm%GetGridCellCount()
 status = brm%OutputMessage(trim(string1))
 write(string1, "(A,I10)") "Number of chemistry cells in the reaction module: ", brm%GetChemistryCellCount()
 status = brm%OutputMessage(trim(string1))
 write(string1, "(A,I10)") "Number of components for transport:               ", brm%GetComponentCount()
 status = brm%OutputMessage(trim(string1))
 

MPI:

Called by root.

RunCells()

integer function BMIPhreeqcRM::RunCells

(

class(bmi), intent(inout)

self

)

Runs a reaction step for all of the cells in the reaction module. Normally, tranport concentrations are transferred to the reaction cells (SetConcentrations) before reaction calculations are run. The length of time over which kinetic reactions are integrated is set by SetTimeStep. Other properties that may need to be updated as a result of the transport calculations include porosity (SetPorosity), saturation (SetSaturationUser), temperature (SetTemperature), and pressure (SetPressure).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetConcentrations, SetPorosity, SetPressure, SetSaturationUser, SetTemperature, SetTimeStep.

Fortran Example:

 status = brm%SetPorosity(por)                ! If pore volume changes
 status = brm%SetSaturationUser(sat)          ! If saturation changes
 status = brm%SetTemperature(temperature)     ! If temperature changes
 status = brm%SetPressure(pressure)           ! If pressure changes
 status = brm%SetConcentrations(c)            ! Transported concentrations
 status = brm%SetTimeStep(time_step)          ! Time step for kinetic reactions
 status = brm%RunCells()
 status = brm%GetConcentrations(c)            ! Concentrations after reaction
 status = brm%GetDensityCalculated(density)   ! Density after reaction
 status = brm%GetSolutionVolume(volume)       ! Solution volume after reaction
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

RunFile()

integer function BMIPhreeqcRM::RunFile	(	class(bmi), intent(inout)	self,
		integer, intent(in)	workers,
		integer, intent(in)	initial_phreeqc,
		integer, intent(in)	utility,
		character(len=*), intent(in)	chem_name
	)

Run a PHREEQC input file. The first three arguments determine which IPhreeqc instances will run the file–the workers, the InitialPhreeqc instance, and (or) the Utility instance. Input files that modify the thermodynamic database should be run by all three sets of instances. Files with SELECTED_OUTPUT definitions that will be used during the time-stepping loop need to be run by the workers. Files that contain initial conditions or boundary conditions should be run by the InitialPhreeqc instance.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
workers	1, the workers will run the file; 0, the workers will not run the file.
initial_phreeqc	1, the InitialPhreeqc instance will run the file; 0, the InitialPhreeqc will not run the file.
utility	1, the Utility instance will run the file; 0, the Utility instance will not run the file.
chem_name	Name of the file to run.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

RunString.

Fortran Example:

 status = brm%RunFile(1, 1, 1, "advect.pqi")
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

RunString()

integer function BMIPhreeqcRM::RunString	(	class(bmi), intent(inout)	self,
		integer, intent(in)	workers,
		integer, intent(in)	initial_phreeqc,
		integer, intent(in)	utility,
		character(len=*), intent(in)	input_string
	)

Run a PHREEQC input string. The first three arguments determine which IPhreeqc instances will run the string–the workers, the InitialPhreeqc instance, and (or) the Utility instance. Input strings that modify the thermodynamic database should be run by all three sets of instances. Strings with SELECTED_OUTPUT definitions that will be used during the time-stepping loop need to be run by the workers. Strings that contain initial conditions or boundary conditions should be run by the InitialPhreeqc instance.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
workers	1, the workers will run the string; 0, the workers will not run the string.
initial_phreeqc	1, the InitialPhreeqc instance will run the string; 0, the InitialPhreeqc will not run the string.
utility	1, the Utility instance will run the string; 0, the Utility instance will not run the string.
input_string	String containing PHREEQC input.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

RunFile.

Fortran Example:

 string = "DELETE; -all"
 status = brm%RunString(1, 0, 1, string)  ! workers, initial_phreeqc, utility
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

ScreenMessage()

integer function BMIPhreeqcRM::ScreenMessage	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	str
	)

Print message to the screen.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
str	String to be printed.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

ErrorMessage, LogMessage, OutputMessage, WarningMessage.

Fortran Example:

 write(string, "(A32,F15.1,A)") "Beginning reaction calculation  ", &
       time * brm%GetTimeconversion(), " days"
 status = brm%ScreenMessage(string)
 

MPI:

Called by root and (or) workers.

SetComponentH2O()

integer function BMIPhreeqcRM::SetComponentH2O	(	class(bmi), intent(inout)	self,
		integer, intent(in)	tf
	)

Select whether to include H2O in the component list. The concentrations of H and O must be known accurately (8 to 10 significant digits) for the numerical method of PHREEQC to produce accurate pH and pe values. Because most of the H and O are in the water species, it may be more robust (require less accuracy in transport) to transport the excess H and O (the H and O not in water) and water. The default setting (true) is to include water, excess H, and excess O as components. A setting of false will include total H and total O as components. SetComponentH2O must be called before FindComponents.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
tf	0, total H and O are included in the component list; 1, excess H, excess O, and water are included in the component list.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents.

Fortran Example:

 status = brm%SetComponentH2O(0)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetConcentrations()

integer function BMIPhreeqcRM::SetConcentrations	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(in)	c
	)

Use the array of concentrations (c) to set the moles of components in each reaction cell. The volume of water in a cell is the product of porosity (SetPorosity), saturation (SetSaturationUser), and reference volume (SetRepresentativeVolume). The moles of each component are determined by the volume of water and per liter concentrations. If concentration units (SetUnitsSolution) are mass fraction, the density (as specified by SetDensityUser) is used to convert from mass fraction to per mass per liter.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
c	Array of component concentrations. Size of array is (nxyz, ncomps), where nxyz is the number of grid cells in the user's model (GetGridCellCount), and ncomps is the number of components as determined by FindComponents or GetComponentCount.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetDensityUser, SetPorosity, SetRepresentativeVolume, SetSaturationUser, SetUnitsSolution.

Fortran Example:

 allocate(c(nxyz, ncomps))
 ...
 call advect_f90(c, bc_conc, ncomps, nxyz)
 status = brm%SetPorosity(por)               ! If porosity changes
 status = brm%SetSaturationUser(sat)         ! If saturation changes
 status = brm%SetTemperature(temperature))   ! If temperature changes
 status = brm%SetPressure(pressure)          ! If pressure changes
 status = brm%SetConcentrations(c)           ! Transported concentrations
 status = brm%SetTimeStep(time_step)         ! Time step for kinetic reactions
 status = brm%SetTime(time)                  ! Current time
 status = brm%RunCells()
 status = brm%GetConcentrations(c)           ! Concentrations after reaction
 status = brm%GetDensityCalculated(density)  ! Density after reaction
 status = brm%GetSolutionVolume(volume)      ! Solution volume after reaction
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetCurrentSelectedOutputUserNumber()

integer function BMIPhreeqcRM::SetCurrentSelectedOutputUserNumber	(	class(bmi), intent(inout)	self,
		integer, intent(in)	n_user
	)

Select the current selected output by user number. The user may define multiple SELECTED_OUTPUT data blocks for the workers. A user number is specified for each data block. The value of the argument n_user selects which of the SELECTED_OUTPUT definitions will be used for selected-output operations.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
n_user	User number of the SELECTED_OUTPUT data block that is to be used.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

GetCurrentSelectedOutputUserNumber, GetNthSelectedOutputUserNumber, GetSelectedOutput, GetSelectedOutputColumnCount, GetSelectedOutputCount, GetSelectedOutputHeadings, GetSelectedOutputRowCount, SetNthSelectedOutput, SetSelectedOutputOn.

Fortran Example:

 real(kind=8), allocatable :: selected_out(:,:)
 do isel = 1, brm%GetSelectedOutputCount()
   n_user = brm%GetNthSelectedOutputUserNumber(isel)
   status = brm%SetCurrentSelectedOutputUserNumber(n_user)
   col = brm%GetSelectedOutputColumnCount()
   status = brm%GetSelectedOutput(selected_out)
   ! Process results here
 enddo
 

MPI:

Called by root.

SetDensity()

integer function BMIPhreeqcRM::SetDensity	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(in)	density
	)

This deprecated function is included for backward compatibility. Use SetDensityUser.

SetDensityUser()

integer function BMIPhreeqcRM::SetDensityUser	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(in)	density
	)

Set the density used for units conversion. These density values are used when converting from transported mass fraction concentrations (SetUnitsSolution) to produce per liter concentrations during a call to SetConcentrations. They are also used when converting from module concentrations to transport concentrations of mass fraction (GetConcentrations), if UseSolutionDensityVolume is set to false.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
density	Array of densities. Size of array is nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

GetConcentrations, SetConcentrations, SetUnitsSolution, UseSolutionDensityVolume.

Fortran Example:

 allocate(density(nxyz))
 density = 1.0
 status = brm%SetDensityUser(density)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetDumpFileName()

integer function BMIPhreeqcRM::SetDumpFileName	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	dump_name
	)

Set the name of the dump file. It is the name used by DumpModule.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
dump_name	Name of dump file.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

DumpModule.

Fortran Example:

 status = brm%SetDumpFileName("advection_f90.dmp")
 dump_on = 1
 append = 0
 status = brm%DumpModule(dump_on, append)
 

MPI:

Called by root.

SetErrorHandlerMode()

integer function BMIPhreeqcRM::SetErrorHandlerMode	(	class(bmi), intent(inout)	self,
		integer, intent(in)	mode
	)

Set the action to be taken when the reaction module encounters an error. Options are 0, return to calling program with an error return code (default); 1, throw an exception, in C++, the exception can be caught, for C and Fortran, the program will exit; or 2, attempt to exit gracefully.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
mode	Error handling mode: 0, 1, or 2.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

Fortran Example:

 id = Create(nxyz, nthreads)
 status = brm%SetErrorHandlerMode(2)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetErrorOn()

integer function BMIPhreeqcRM::SetErrorOn	(	class(bmi), intent(inout)	self,
		integer, intent(in)	tf
	)

Set the property that controls whether error messages are generated and displayed. Messages include PHREEQC "ERROR" messages, and any messages written with ErrorMessage.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
tf	1, enable error messages; 0, disable error messages. Default is 1.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

ErrorMessage, ScreenMessage.

Fortran Example:

 status = brm%SetErrorOn(1)
 

MPI:

Called by root.

SetFilePrefix()

integer function BMIPhreeqcRM::SetFilePrefix	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	prefix
	)

Set the prefix for the output (prefix.chem.txt) and log (prefix.log.txt) files. These files are opened by OpenFiles.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
prefix	Prefix used when opening the output and log files.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

OpenFiles, CloseFiles.

Fortran Example:

 status = brm%SetFilePrefix("Advect_f90")
 status = brm%OpenFiles()
 

MPI:

Called by root.

SetGasCompMoles()

integer function BMIPhreeqcRM::SetGasCompMoles	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(in)	gas_moles
	)

Use the array of concentrations (gas_moles) to set the moles of gas components in each reaction cell.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
gas_moles	Array of moles of gas components. Dimensions of the array are (nxyz, ngas_comps), where ngas_comps is the result of GetGasComponentsCount, and nxyz is the number of user grid cells (GetGridCellCount). If the number of moles is set to a negative number, the gas component will not be defined for the GAS_PHASE of the reaction cell.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetGasComponentsCount, GetGasCompMoles, GetGasCompPressures, GetGasCompPhi, GetGasPhaseVolume, SetGasPhaseVolume.

Fortran Example:

 ngas_comps = brm%SetGasComponentsCount()
 allocate(gas_moles(nxyz, ngas_comps))
 ...
 status = brm%SetGasCompMoles(gas_moles)
 status = brm%RunCells()
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetGasPhaseVolume()

integer function BMIPhreeqcRM::SetGasPhaseVolume	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(in)	gas_volume
	)

Transfer volumes of gas phases from the array given in the argument list (gas_volume) to each reaction cell. The gas-phase volume affects the pressures calculated for fixed-volume gas phases. If a gas-phase volume is defined with this method for a GAS_PHASE in a cell, the gas phase is forced to be a fixed-volume gas phase.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
gas_volume	Array of gas-phase volumes. Dimension of the array is (nxyz), where nxyz is the number of user grid cells (GetGridCellCount). If an element of the array is set to a negative number, the gas component will not be defined for the GAS_PHASE of the reaction cell.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetGasComponentsCount, GetGasCompMoles, GetGasCompPressures, GetGasCompPhi, GetGasPhaseVolume, SetGasCompMoles.

Fortran Example:

 allocate(gas_volume(nxyz))
 ...
 status = brm%SetGasPhaseVolume(gas_volume)
 status = brm%RunCells()
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetIthConcentration()

integer function BMIPhreeqcRM::SetIthConcentration	(	class(bmi), intent(inout)	self,
		integer, intent(in)	i,
		real(kind=8), dimension(:), intent(in)	c
	)

Transfer the concentrations for one component given by the vector c to each reaction cell. Units of concentration for c are defined by SetUnitsSolution. It is required that SetIthConcentration be called for each component in the system before RunCells is called.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
i	One-based index for the component to transfer. Indices refer to the order produced by GetComponents. The total number of components is given by GetComponentCount.
c	Array of concentrations to transfer to the reaction cells. Dimension of the vector is nxyz, where nxyz is the number of user grid cells (GetGridCellCount). Values for inactive cells are ignored.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetComponentCount, GetComponents, SetConcentrations.

Fortran Example:

 status = brm%phreeqc_rm.SetIthConcentration(i, c) ! repeat for all components
 ...
 status = brm%phreeqc_rm.RunCells()
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetIthSpeciesConcentration()

integer function BMIPhreeqcRM::SetIthSpeciesConcentration	(	class(bmi), intent(inout)	self,
		integer, intent(in)	i,
		real(kind=8), dimension(:), intent(in)	c
	)

Transfer the concentrations for one aqueous species given by the vector c to each reaction cell. Units of concentration for c are mol/L. To set species concentrations, SetSpeciesSaveOn must be set to true. It is required that SetIthSpeciesConcentration be called for each aqueous species in the system before RunCells is called. This method is for use with multicomponent diffusion calculations.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
i	One-based index for the species to transfer. Indices refer to the order produced by GetSpeciesNames. The total number of species is given by GetSpeciesCount.
c	Array of concentrations to transfer to the reaction cells. Dimension of the array is nxyz, where nxyz is the number of user grid cells (GetGridCellCount). Values for inactive cells are ignored.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesCount, GetSpeciesNames, SpeciesConcentrations2Module, SetSpeciesSaveOn.

Fortran Example:

 status = brm%SetIthSpeciesConcentration(i, c) ! repeat for all species
 ...
 status = brm%RunCells()
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetMpiWorkerCallback()

integer function BMIPhreeqcRM::SetMpiWorkerCallback	(	class(bmi), intent(inout)	self,
		external integer(kind=c_int) function(integer(kind=c_int), intent(in) method_number)	fcn
	)

MPI only. Defines a callback function that allows additional tasks to be done by the workers. The method MpiWorker contains a loop, where the workers receive a message (an integer), run a function corresponding to that integer, and then wait for another message. SetMpiWorkerCallback allows the developer to add another function that responds to additional integer messages by calling developer-defined functions corresponding to those integers. MpiWorker calls the callback function when the message number is not one of the PhreeqcRM message numbers. Messages are unique integer numbers. PhreeqcRM uses integers in a range beginning at 0. It is suggested that developers use message numbers starting at 1000 or higher for their tasks. The callback function calls a developer-defined function specified by the message number and then returns to MpiWorker to wait for another message.

For Fortran, the functions that are called from the callback function can use USE statements to find the data necessary to perform the tasks, and the only argument to the callback function is an integer message argument. SetMpiWorkerCallback must be called by each worker before MpiWorker is called.

The motivation for this method is to allow the workers to perform other tasks, for instance, parallel transport calculations, within the structure of MpiWorker. The callback function can be used to allow the workers to receive data, perform transport calculations, and (or) send results, without leaving the loop of MpiWorker. Alternatively, it is possible for the workers to return from MpiWorker by a call to MpiWorkerBreak by root. The workers could then call subroutines to receive data, calculate transport, and send data, and then resume processing PhreeqcRM messages from root with another call to MpiWorker.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
fcn	A function that returns an integer and has an integer argument.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

MpiWorker, MpiWorkerBreak.

Fortran Example:

 Code executed by root:
 status = do_something()

 Code executed by workers:
 status = brm%SetMpiWorkerCallback(worker_tasks_f)
 status = brm%MpiWorker()

 Code executed by root and workers:
 integer function do_something
   implicit none
   INCLUDE 'mpif.h'
   integer status
   integer i, method_number, mpi_myself, mpi_task, mpi_tasks, worker_number;
   method_number = 1000
   call MPI_Comm_size(MPI_COMM_WORLD, mpi_tasks, status)
   call MPI_Comm_rank(MPI_COMM_WORLD, mpi_myself, status)
   if (mpi_myself .eq. 0) then
     CALL MPI_Bcast(method_number, 1, MPI_INTEGER, 0, MPI_COMM_WORLD, status)
     write(*,*) "I am root."
     do i = 1, mpi_tasks-1
       CALL MPI_Recv(worker_number, 1, MPI_INTEGER, i, 0, MPI_COMM_WORLD, MPI_STATUS_IGNORE, status)
       write(*,*) "Recieved data from worker number ", worker_number, "."
     enddo
   else
     CALL MPI_Send(mpi_myself, 1, MPI_INTEGER, 0, 0, MPI_COMM_WORLD, status)
   endif
   do_something = 0
 end function do_something

 Code called by workers from method MpiWorker:
 integer(kind=C_INT) function worker_tasks_f(method_number) BIND(C, NAME='worker_tasks_f')
   USE ISO_C_BINDING
   implicit none
   interface
     integer function do_something
     end function do_something
   end interface
   integer(kind=c_int), INTENT(inout) :: method_number
   integer :: status
   if (method_number .eq. 1000) then
     status = do_something()
   endif
   worker_tasks_f = 0
 end function worker_tasks_f
 

MPI:

Called by workers, before call to MpiWorker.

SetNthSelectedOutput()

integer function BMIPhreeqcRM::SetNthSelectedOutput	(	class(bmi), intent(inout)	self,
		integer, intent(in)	n
	)

Specify the current selected output by sequence number. The user may define multiple SELECTED_OUTPUT data blocks for the workers. A user number is specified for each data block, and the blocks are stored in user-number order. The value of the argument n selects the sequence number of the SELECTED_OUTPUT definition that will be used for selected-output operations.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
n	Sequence number of the SELECTED_OUTPUT data block that is to be used.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

GetCurrentSelectedOutputUserNumber, GetNthSelectedOutputUserNumber, GetSelectedOutput, GetSelectedOutputColumnCount, GetSelectedOutputCount, GetSelectedOutputHeadings, GetSelectedOutputRowCount, SetCurrentSelectedOutputUserNumber, SetSelectedOutputOn.

Fortran Example:

 do isel = 1, brm%GetSelectedOutputCount()
   status = brm%SetNthSelectedOutput(isel)
   n_user = brm%GetCurrentSelectedOutputUserNumber()
   col = brm%GetSelectedOutputColumnCount()
   allocate(selected_out(nxyz,col))
   status = brm%GetSelectedOutput(selected_out)
   ! Process results here
   deallocate(selected_out)
 enddo
 

MPI:

Called by root.

SetPartitionUZSolids()

integer function BMIPhreeqcRM::SetPartitionUZSolids	(	class(bmi), intent(inout)	self,
		integer, intent(in)	tf
	)

Sets the property for partitioning solids between the saturated and unsaturated parts of a partially saturated cell. The option is intended to be used by saturated-only flow codes that allow a variable water table. The value has meaning only when saturations less than 1.0 are encountered. The partially saturated cells may have a small water-to-rock ratio that causes reactions to proceed differently relative to fully saturated cells. By setting
SetPartitionUZSolids to true, the amounts of solids and gases are partioned according to the saturation. If a cell has a saturation of 0.5, then the water interacts with only half of the solids and gases; the other half is unreactive until the water table rises. As the saturation in a cell varies, solids and gases are transferred between the saturated and unsaturated (unreactive) reservoirs of the cell. Unsaturated-zone flow and transport codes will probably use the default (false), which assumes all gases and solids are reactive regardless of saturation.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
tf	True, the fraction of solids and gases available for reaction is equal to the saturation; False (default), all solids and gases are reactive regardless of saturation.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

Fortran Example:

 status = brm%SetPartitionUZSolids(0)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetPorosity()

integer function BMIPhreeqcRM::SetPorosity	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(in)	por
	)

Set the porosity for each reaction cell. The volume of water in a reaction cell is the product of the porosity, the saturation (SetSaturationUser), and the representative volume (SetRepresentativeVolume).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
por	Array of porosities, unitless. Default is 0.1. Size of array is nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

GetSaturationCalculated, SetRepresentativeVolume, SetSaturationUser.

Fortran Example:

 allocate(por(nxyz))
 por = 0.2
 status = brm%SetPorosity(por)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetPressure()

integer function BMIPhreeqcRM::SetPressure	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(in)	p
	)

Set the pressure for each reaction cell. Pressure effects are considered explicitly only in three of the databases distributed with PhreeqcRM: phreeqc.dat, Amm.dat, and pitzer.dat.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
p	Array of pressures, in atm. Size of array is nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetTemperature.

Fortran Example:

 allocate(pressure(nxyz))
 pressure = 2.0
 status = brm%SetPressure(pressure)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetPrintChemistryMask()

integer function BMIPhreeqcRM::SetPrintChemistryMask	(	class(bmi), intent(inout)	self,
		integer, dimension(:), intent(in)	cell_mask
	)

Enable or disable detailed output for each reaction cell. Printing for a cell will occur only when the printing is enabled with SetPrintChemistryOn and the cell_mask value is 1.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
cell_mask	Array of integers. Size of array is nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount). A value of 0 will disable printing detailed output for the cell; a value of 1 will enable printing detailed output for a cell.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetPrintChemistryOn.

Fortran Example:

 allocate(print_chemistry_mask(nxyz))
   do i = 1, nxyz/2
   print_chemistry_mask(i) = 1
   print_chemistry_mask(i+nxyz/2) = 0
 enddo
 status = brm%SetPrintChemistryMask(print_chemistry_mask)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetPrintChemistryOn()

integer function BMIPhreeqcRM::SetPrintChemistryOn	(	class(bmi), intent(inout)	self,
		integer, intent(in)	workers,
		integer, intent(in)	initial_phreeqc,
		integer, intent(in)	utility
	)

Setting to enable or disable printing detailed output from reaction calculations to the output file for a set of cells defined by SetPrintChemistryMask. The detailed output prints all of the output typical of a PHREEQC reaction calculation, which includes solution descriptions and the compositions of all other reactants. The output can be several hundred lines per cell, which can lead to a very large output file (prefix.chem.txt, OpenFiles). For the worker instances, the output can be limited to a set of cells (SetPrintChemistryMask) and, in general, the amount of information printed can be limited by use of options in the PRINT data block of PHREEQC (applied by using RunFile or RunString). Printing the detailed output for the workers is generally used only for debugging, and PhreeqcRM will run significantly faster when printing detailed output for the workers is disabled.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
workers	0, disable detailed printing in the worker instances; 1, enable detailed printing in the worker instances.
initial_phreeqc	0, disable detailed printing in the InitialPhreeqc instance; 1, enable detailed printing in the InitialPhreeqc instances.
utility	0, disable detailed printing in the Utility instance; 1, enable detailed printing in the Utility instance.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetPrintChemistryMask.

Fortran Example:

 status = brm%SetPrintChemistryOn(0, 1, 0)  ! workers, initial_phreeqc, utility
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetRebalanceByCell()

integer function BMIPhreeqcRM::SetRebalanceByCell	(	class(bmi), intent(inout)	self,
		integer, intent(in)	method
	)

Set the load-balancing algorithm. PhreeqcRM attempts to rebalance the load of each thread or process such that each thread or process takes the same amount of time to run its part of a RunCells calculation. Two algorithms are available; one uses individual times for each cell and accounts for cells that were not run because saturation was zero (default), and the other assigns an average time to all cells. The methods are similar, but limited testing indicates the default method performs better.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
method	0, indicates average times are used in rebalancing; 1 indicates individual cell times are used in rebalancing (default).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetRebalanceFraction.

Fortran Example:

 status = brm%SetRebalanceByCell(1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetRebalanceFraction()

integer function BMIPhreeqcRM::SetRebalanceFraction	(	class(bmi), intent(inout)	self,
		real(kind=8), intent(in)	f
	)

Sets the fraction of cells that are transferred among threads or processes when rebalancing. PhreeqcRM attempts to rebalance the load of each thread or process such that each thread or process takes the same amount of time to run its part of a RunCells calculation. The rebalancing transfers cell calculations among threads or processes to try to achieve an optimum balance. SetRebalanceFraction adjusts the calculated optimum number of cell transfers by a fraction from 0 to 1.0 to determine the actual number of cell transfers. A value of zero eliminates load rebalancing. A value less than 1.0 is suggested to slow the approach to the optimum cell distribution and avoid possible oscillations when too many cells are transferred at one iteration, requiring reverse transfers at the next iteration. Default is 0.5.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
f	Fraction from 0.0 to 1.0.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetRebalanceByCell.

Fortran Example:

 status = brm%SetRebalanceFraction(0.5d0)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetRepresentativeVolume()

integer function BMIPhreeqcRM::SetRepresentativeVolume	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(in)	rv
	)

Set the representative volume of each reaction cell. By default the representative volume of each reaction cell is 1 liter. The volume of water in a reaction cell is determined by the procuct of the representative volume, the porosity (SetPorosity), and the saturation (SetSaturationUser). The numerical method of PHREEQC is more robust if the water volume for a reaction cell is within a couple orders of magnitude of 1.0. Small water volumes caused by small porosities and (or) small saturations (and (or) small representative volumes) may cause non-convergence of the numerical method. In these cases, a larger representative volume may help. Note that increasing the representative volume also increases the number of moles of the reactants in the reaction cell (minerals, surfaces, exchangers, and others).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
rv	Vector of representative volumes, in liters. Default is 1.0 liter. Size of array is nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetPorosity, SetSaturationUser.

Fortran Example:

 real(kind=8), dimension(:), allocatable   :: rv
 allocate(rv(nxyz))
 rv = 1.0
 status = brm%SetRepresentativeVolume(rv)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetSaturation()

integer function BMIPhreeqcRM::SetSaturation	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(in)	sat
	)

This deprecated function is included for backward compatibility. Use SetSaturationUser.

SetSaturationUser()

integer function BMIPhreeqcRM::SetSaturationUser	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(in)	sat
	)

Set the saturation of each reaction cell. Saturation is a fraction ranging from 0 to 1. The volume of water in a cell is the product of porosity (SetPorosity), saturation (SetSaturationUser), and representative volume (SetRepresentativeVolume). As a result of a reaction calculation, solution properties (density and volume) will change; the databases phreeqc.dat, Amm.dat, and pitzer.dat have the molar volume data to calculate these changes. The methods GetDensityCalculated, GetSolutionVolume, and GetSaturationCalculated can be used to account for these changes in the succeeding transport calculation. SetRepresentativeVolume should be called before initial conditions are defined for the reaction cells.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
sat	Array of saturations, unitless. Size of array is nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

GetDensityCalculated, GetSaturationCalculated, GetSolutionVolume, SetPorosity, SetRepresentativeVolume.

Fortran Example:

 allocate(sat(nxyz))
 sat = 1.0
 status = brm%SetSaturationUser(sat)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetScreenOn()

integer function BMIPhreeqcRM::SetScreenOn	(	class(bmi), intent(inout)	self,
		integer, intent(in)	tf
	)

Set the property that controls whether messages are written to the screen. Messages include information about rebalancing during RunCells, and any messages written with ScreenMessage.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
tf	1, enable screen messages; 0, disable screen messages. Default is 1.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

RunCells, ScreenMessage.

Fortran Example:

 status = brm%SetScreenOn(1)
 

MPI:

Called by root.

SetSelectedOutputOn()

integer function BMIPhreeqcRM::SetSelectedOutputOn	(	class(bmi), intent(inout)	self,
		integer, intent(in)	tf
	)

Setting determines whether selected-output results are available to be retrieved with GetSelectedOutput. 1 indicates that selected-output results will be accumulated during RunCells and can be retrieved with GetSelectedOutput; 0 indicates that selected-output results will not be accumulated during RunCells.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
tf	0, disable selected output; 1, enable selected output.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

GetCurrentSelectedOutputUserNumber, GetNthSelectedOutputUserNumber, GetSelectedOutput, GetSelectedOutputColumnCount, GetSelectedOutputCount, GetSelectedOutputHeadings, GetSelectedOutputRowCount, SetCurrentSelectedOutputUserNumber, SetNthSelectedOutput.

Fortran Example:

 status = brm%SetSelectedOutputOn(1)        ! enable selected output
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetSpeciesSaveOn()

integer function BMIPhreeqcRM::SetSpeciesSaveOn	(	class(bmi), intent(inout)	self,
		integer, intent(in)	save_on
	)

Sets the value of the species-save property. This method enables use of PhreeqcRM with multicomponent-diffusion transport calculations. By default, concentrations of aqueous species are not saved. Setting the species-save property to 1 allows aqueous species concentrations to be retrieved with GetSpeciesConcentrations, and solution compositions to be set with SpeciesConcentrations2Module. SetSpeciesSaveOn must be called before calls to FindComponents.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
save_on	0, indicates species concentrations are not saved; 1, indicates species concentrations are saved.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesConcentrations, GetSpeciesCount, GetSpeciesD25, GetSpeciesLog10Gammas, GetSpeciesLog10Molalities, GetSpeciesNames, GetSpeciesSaveOn, GetSpeciesZ, SpeciesConcentrations2Module.

Fortran Example:

 save_on = brm%SetSpeciesSaveOn(1)
 

MPI:

Called by root and (or) workers.

SetTemperature()

integer function BMIPhreeqcRM::SetTemperature	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:), intent(in)	t
	)

Set the temperature for each reaction cell. If SetTemperature is not called, worker solutions will have temperatures as defined by initial conditions (InitialPhreeqc2Module and InitialPhreeqcCell2Module).

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
t	Array of temperatures, in degrees C. Size of array is nxyz, where nxyz is the number of grid cells in the user's model (GetGridCellCount).

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialPhreeqc2Module, InitialPhreeqcCell2Module, SetPressure.

Fortran Example:

 allocate(temperature(nxyz))
 temperature = 20.0
 status = brm%SetTemperature(temperature)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetTime()

integer function BMIPhreeqcRM::SetTime	(	class(bmi), intent(inout)	self,
		real(kind=8), intent(in)	time
	)

Set current simulation time for the reaction module.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
time	Current simulation time, in seconds.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetTimeConversion, SetTimeStep.

Fortran Example:

 status = brm%SetTime(time)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetTimeConversion()

integer function BMIPhreeqcRM::SetTimeConversion	(	class(bmi), intent(inout)	self,
		real(kind=8), intent(in)	conv_factor
	)

Set a factor to convert to user time units. Factor times seconds produces user time units.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
conv_factor	Factor to convert seconds to user time units.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetTime, SetTimeStep.

Fortran Example:

 status = brm%SetTimeConversion(dble(1.0 / 86400.0)) ! days
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetTimeStep()

integer function BMIPhreeqcRM::SetTimeStep	(	class(bmi), intent(inout)	self,
		real(kind=8), intent(in)	time_step
	)

Set current time step for the reaction module. This is the length of time over which kinetic reactions are integrated.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
time_step	Current time step, in seconds.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetTime, SetTimeConversion.

Fortran Example:

 status = brm%SetTimeStep(time_step)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetUnitsExchange()

integer function BMIPhreeqcRM::SetUnitsExchange	(	class(bmi), intent(inout)	self,
		integer, intent(in)	option
	)

Sets input units for exchangers. In PHREEQC input, exchangers are defined by moles of exchange sites (Mp). SetUnitsExchange specifies how the number of moles of exchange sites in a reaction cell (Mc) is calculated from the input value (Mp).

Options are 0, Mp is mol/L of RV (default), Mc = Mp*RV, where RV is the representative volume (SetRepresentativeVolume); 1, Mp is mol/L of water in the RV, Mc = Mp*P*RV, where P is porosity (SetPorosity); or 2, Mp is mol/L of rock in the RV, Mc = Mp*(1-P)*RV.

If a single EXCHANGE definition is used for cells with different initial porosity, the three options scale quite differently. For option 0, the number of moles of exchangers will be the same regardless of porosity. For option 1, the number of moles of exchangers will be vary directly with porosity and inversely with rock volume. For option 2, the number of moles of exchangers will vary directly with rock volume and inversely with porosity.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
option	Units option for exchangers: 0, 1, or 2.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialPhreeqc2Module, InitialPhreeqcCell2Module, SetPorosity, SetRepresentativeVolume.

Fortran Example:

 status = brm%SetUnitsExchange(1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetUnitsGasPhase()

integer function BMIPhreeqcRM::SetUnitsGasPhase	(	class(bmi), intent(inout)	self,
		integer, intent(in)	option
	)

Set input units for gas phases. In PHREEQC input, gas phases are defined by moles of component gases (Mp). SetUnitsGasPhase specifies how the number of moles of component gases in a reaction cell (Mc) is calculated from the input value (Mp).

Options are 0, Mp is mol/L of RV (default), Mc = Mp*RV, where RV is the representative volume (SetRepresentativeVolume); 1, Mp is mol/L of water in the RV, Mc = Mp*P*RV, where P is porosity (SetPorosity); or 2, Mp is mol/L of rock in the RV, Mc = Mp*(1-P)*RV.

If a single GAS_PHASE definition is used for cells with different initial porosity, the three options scale quite differently. For option 0, the number of moles of a gas component will be the same regardless of porosity. For option 1, the number of moles of a gas component will be vary directly with porosity and inversely with rock volume. For option 2, the number of moles of a gas component will vary directly with rock volume and inversely with porosity.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
option	Units option for gas phases: 0, 1, or 2.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialPhreeqc2Module, InitialPhreeqcCell2Module, SetPorosity, SetRepresentativeVolume.

Fortran Example:

 status = brm%SetUnitsGasPhase(1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetUnitsKinetics()

integer function BMIPhreeqcRM::SetUnitsKinetics	(	class(bmi), intent(inout)	self,
		integer, intent(in)	option
	)

Set input units for kinetic reactants. In PHREEQC input, kinetics are defined by moles of kinetic reactants (Mp). SetUnitsKinetics specifies how the number of moles of kinetic reactants in a reaction cell (Mc) is calculated from the input value (Mp).

Options are 0, Mp is mol/L of RV (default), Mc = Mp*RV, where RV is the representative volume (SetRepresentativeVolume); 1, Mp is mol/L of water in the RV, Mc = Mp*P*RV, where P is porosity (SetPorosity); or 2, Mp is mol/L of rock in the RV, Mc = Mp*(1-P)*RV.

If a single KINETICS definition is used for cells with different initial porosity, the three options scale quite differently. For option 0, the number of moles of kinetic reactants will be the same regardless of porosity. For option 1, the number of moles of kinetic reactants will be vary directly with porosity and inversely with rock volume. For option 2, the number of moles of kinetic reactants will vary directly with rock volume and inversely with porosity.

Note that the volume of water in a cell in the reaction module is equal to the product of porosity (SetPorosity), the saturation (SetSaturationUser), and representative volume (SetRepresentativeVolume), which is usually less than 1 liter. It is important to write the RATES definitions for homogeneous (aqueous) kinetic reactions to account for the current volume of water, often by calculating the rate of reaction per liter of water and multiplying by the volume of water (Basic function SOLN_VOL).

Rates that depend on surface area of solids, are not dependent on the volume of water. However, it is important to get the correct surface area for the kinetic reaction. To scale the surface area with the number of moles, the specific area (m^2 per mole of reactant) can be defined as a parameter (KINETICS; -parm), which is multiplied by the number of moles of reactant (Basic function M) in RATES to obtain the surface area.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
option	Units option for kinetic reactants: 0, 1, or 2.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialPhreeqc2Module, InitialPhreeqcCell2Module, SetPorosity, SetRepresentativeVolume, SetSaturationUser.

Fortran Example:

 status = brm%SetUnitsKinetics(1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetUnitsPPassemblage()

integer function BMIPhreeqcRM::SetUnitsPPassemblage	(	class(bmi), intent(inout)	self,
		integer, intent(in)	option
	)

Set input units for pure phase assemblages (equilibrium phases). In PHREEQC input, equilibrium phases are defined by moles of each phase (Mp). SetUnitsPPassemblage specifies how the number of moles of phases in a reaction cell (Mc) is calculated from the input value (Mp).

Options are 0, Mp is mol/L of RV (default), Mc = Mp*RV, where RV is the representative volume (SetRepresentativeVolume); 1, Mp is mol/L of water in the RV, Mc = Mp*P*RV, where P is porosity (SetPorosity); or 2, Mp is mol/L of rock in the RV, Mc = Mp*(1-P)*RV.

If a single EQUILIBRIUM_PHASES definition is used for cells with different initial porosity, the three options scale quite differently. For option 0, the number of moles of a mineral will be the same regardless of porosity. For option 1, the number of moles of a mineral will be vary directly with porosity and inversely with rock volume. For option 2, the number of moles of a mineral will vary directly with rock volume and inversely with porosity.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
option	Units option for equilibrium phases: 0, 1, or 2.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialPhreeqc2Module, InitialPhreeqcCell2Module, SetPorosity, SetRepresentativeVolume.

Fortran Example:

 status = brm%SetUnitsPPassemblage(1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetUnitsSolution()

integer function BMIPhreeqcRM::SetUnitsSolution	(	class(bmi), intent(inout)	self,
		integer, intent(in)	option
	)

Solution concentration units used by the transport model. Options are 1, mg/L; 2 mol/L; or 3, mass fraction, kg/kgs. PHREEQC defines solutions by the number of moles of each element in the solution.

To convert from mg/L to moles of element in the representative volume of a reaction cell, mg/L is converted to mol/L and multiplied by the solution volume, which is the product of porosity (SetPorosity), saturation (SetSaturationUser), and representative volume (SetRepresentativeVolume). To convert from mol/L to moles of element in the representative volume of a reaction cell, mol/L is multiplied by the solution volume. To convert from mass fraction to moles of element in the representative volume of a reaction cell, kg/kgs is converted to mol/kgs, multiplied by density (SetDensityUser) and multiplied by the solution volume.

To convert from moles of element in the representative volume of a reaction cell to mg/L, the number of moles of an element is divided by the solution volume resulting in mol/L, and then converted to mg/L. To convert from moles of element in a cell to mol/L, the number of moles of an element is divided by the solution volume resulting in mol/L.

To convert from moles of element in a cell to mass fraction, the number of moles of an element is converted to kg and divided by the total mass of the solution. Two options are available for the volume and mass of solution that are used in converting to transport concentrations: (1) the volume and mass of solution are calculated by PHREEQC, or (2) the volume of solution is the product of porosity (SetPorosity), saturation (SetSaturationUser), and representative volume (SetRepresentativeVolume), and the mass of solution is volume times density as defined by SetDensityUser. Which option is used is determined by UseSolutionDensityVolume.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
option	Units option for solutions: 1, 2, or 3, default is 1, mg/L.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

SetDensityUser, SetPorosity, SetRepresentativeVolume, SetSaturationUser, UseSolutionDensityVolume.

Fortran Example:

 status = brm%SetUnitsSolution(1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetUnitsSSassemblage()

integer function BMIPhreeqcRM::SetUnitsSSassemblage	(	class(bmi), intent(inout)	self,
		integer, intent(in)	option
	)

Set input units for solid-solution assemblages. In PHREEQC, solid solutions are defined by moles of each component (Mp). SetUnitsSSassemblage specifies how the number of moles of solid-solution components in a reaction cell (Mc) is calculated from the input value (Mp).

Options are 0, Mp is mol/L of RV (default), Mc = Mp*RV, where RV is the representative volume (SetRepresentativeVolume); 1, Mp is mol/L of water in the RV, Mc = Mp*P*RV, where P is porosity (SetPorosity); or 2, Mp is mol/L of rock in the RV, Mc = Mp*(1-P)*RV.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
option	Units option for solid solutions: 0, 1, or 2.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialPhreeqc2Module, InitialPhreeqcCell2Module, SetPorosity, SetRepresentativeVolume. If a single SOLID_SOLUTION definition is used for cells with different initial porosity, the three options scale quite differently. For option 0, the number of moles of a solid-solution component will be the same regardless of porosity. For option 1, the number of moles of a solid-solution component will be vary directly with porosity and inversely with rock volume. For option 2, the number of moles of a solid-solution component will vary directly with rock volume and inversely with porosity.

Fortran Example:

 status = brm%SetUnitsSSassemblage(1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SetUnitsSurface()

integer function BMIPhreeqcRM::SetUnitsSurface	(	class(bmi), intent(inout)	self,
		integer, intent(in)	option
	)

Set input units for surfaces. In PHREEQC input, surfaces are defined by moles of surface sites (Mp). SetUnitsSurface specifies how the number of moles of surface sites in a reaction cell (Mc) is calculated from the input value (Mp).

Options are 0, Mp is mol/L of RV (default), Mc = Mp*RV, where RV is the representative volume (SetRepresentativeVolume); 1, Mp is mol/L of water in the RV, Mc = Mp*P*RV, where P is porosity (SetPorosity); or 2, Mp is mol/L of rock in the RV, Mc = Mp*(1-P)*RV.

If a single SURFACE definition is used for cells with different initial porosity, the three options scale quite differently. For option 0, the number of moles of surface sites will be the same regardless of porosity. For option 1, the number of moles of surface sites will be vary directly with porosity and inversely with rock volume. For option 2, the number of moles of surface sites will vary directly with rock volume and inversely with porosity.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
option	Units option for surfaces: 0, 1, or 2.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

InitialPhreeqc2Module, InitialPhreeqcCell2Module, SetPorosity, SetRepresentativeVolume.

Fortran Example:

 status = brm%SetUnitsSurface(1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

SpeciesConcentrations2Module()

integer function BMIPhreeqcRM::SpeciesConcentrations2Module	(	class(bmi), intent(inout)	self,
		real(kind=8), dimension(:,:), intent(in)	species_conc
	)

Set solution concentrations in the reaction cells based on the array of aqueous species concentrations (species_conc). This method is intended for use with multicomponent-diffusion transport calculations, and SetSpeciesSaveOn must be set to true. The list of aqueous species is determined by FindComponents and includes all aqueous species that can be made from the set of components. The method determines the total concentration of a component by summing the molarities of the individual species times the stoichiometric coefficient of the element in each species. Solution compositions in the reaction cells are updated with these component concentrations.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
species_conc	Array of aqueous species concentrations. Dimension of the array is (nxyz, nspecies), where nxyz is the number of user grid cells (GetGridCellCount), and nspecies is the number of aqueous species (GetSpeciesCount). Concentrations are moles per liter.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

FindComponents, GetSpeciesConcentrations, GetSpeciesCount, GetSpeciesD25, GetSpeciesLog10Gammas, GetSpeciesLog10Molalities, GetSpeciesNames, GetSpeciesSaveOn, GetSpeciesZ, SetSpeciesSaveOn.

Fortran Example:

 status = brm%SetSpeciesSaveOn(1)
 ncomps = brm%FindComponents()
 nspecies = brm%GetSpeciesCount()
 nxyz = brm%GetGridCellCount()
 allocate(species_c(nxyz, nspecies))
 ...
 status = brm%SpeciesConcentrations2Module(species_c(1,1))
 status = brm%RunCells()
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

StateApply()

integer function BMIPhreeqcRM::StateApply	(	class(bmi), intent(inout)	self,
		integer, intent(in)	istate
	)

Reset the state of the module to a state previously saved with StateSave. The chemistry of all model cells are reset, including SOLUTIONs, EQUILIBRIUM_PHASES, EXCHANGEs, GAS_PHASEs, KINETICS, SOLID_SOLUTIONs, and SURFACEs. MIXes, REACTIONs, REACTION_PRESSUREs, and REACTION_TEMPERATUREs will be reset for each cell, if they were defined in the worker IPhreeqc instances at the time the state was saved. The distribution of cells among the workers and the chemistry of fully or partially unsaturated cells are also reset to the saved state. The state to be applied is identified by an integer.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance..
istate	Integer identifying the state that is to be applied.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

StateSave and StateDelete.

Fortran Example:

 status = brm%StateSave(1)
 ...
 status = brm%StateApply(1)
 status = brm%StateDelete(1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

StateDelete()

integer function BMIPhreeqcRM::StateDelete	(	class(bmi), intent(inout)	self,
		integer, intent(in)	istate
	)

Delete a state previously saved with StateSave.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
istate	Integer identifying the state that is to be deleted.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

StateSave and ref StateApply.

Fortran Example:

 status = brm%StateSave(1)
 ...
 status = brm%StateApply(1)
 status = brm%StateDelete(1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

StateSave()

integer function BMIPhreeqcRM::StateSave	(	class(bmi), intent(inout)	self,
		integer, intent(in)	istate
	)

Save the state of the chemistry in all model cells, including SOLUTIONs, EQUILIBRIUM_PHASES, EXCHANGEs, GAS_PHASEs, KINETICS, SOLID_SOLUTIONs, and SURFACEs. Although not generally used, MIXes, REACTIONs, REACTION_PRESSUREs, and REACTION_TEMPERATUREs will be saved for each cell, if they have been defined in the worker IPhreeqc instances. The distribution of cells among the workers and the chemistry of fully or partially unsaturated cells are also saved. The state is saved in memory; use DumpModule to save the state to file. PhreeqcRM can be reset to this state by using StateApply. A state is identified by an integer, and multiple states can be saved.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
istate	Integer identifying the state that is saved.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

DumpModule, StateApply, and StateDelete.

Fortran Example:

 status = brm%StateSave(1)
 ...
 status = brm%StateApply(1)
 status = brm%StateDelete(1)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

UseSolutionDensityVolume()

integer function BMIPhreeqcRM::UseSolutionDensityVolume	(	class(bmi), intent(inout)	self,
		integer, intent(in)	tf
	)

Determines the volume and density to use when converting from the reaction-module concentrations to transport concentrations (GetConcentrations). Two options are available to convert concentration units: (1) the density and solution volume calculated by PHREEQC are used, or (2) the specified density (SetDensityUser) and solution volume are defined by the product of saturation (SetSaturationUser), porosity (SetPorosity), and representative volume (SetRepresentativeVolume). Transport models that consider density-dependent flow will probably use the PHREEQC-calculated density and solution volume (default), whereas transport models that assume constant-density flow will probably use specified values of density and solution volume. Only the following databases distributed with PhreeqcRM have molar volume information needed to accurately calculate density and solution volume: phreeqc.dat, Amm.dat, and pitzer.dat. Density is only used when converting to transport units of mass fraction.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
tf	True indicates that the solution density and volume as calculated by PHREEQC will be used to calculate concentrations. False indicates that the solution density set by SetDensityUser and the volume determined by the product of SetSaturationUser, SetPorosity, and SetRepresentativeVolume, will be used to calculate concentrations retrieved by GetConcentrations.

See also

GetConcentrations, SetDensityUser, SetPorosity, SetRepresentativeVolume, SetSaturationUser.

Fortran Example:

 status = brm%UseSolutionDensityVolume(0)
 

MPI:

Called by root, workers must be in the loop of MpiWorker.

WarningMessage()

integer function BMIPhreeqcRM::WarningMessage	(	class(bmi), intent(inout)	self,
		character(len=*), intent(in)	warn_str
	)

Print a warning message to the screen and the log file.

Parameters

self	Fortran-supplied BMIPhreeqcRM instance.
warn_str	String to be printed.

Return values

IRESULT

0 is success, negative is failure (See DecodeError).

See also

ErrorMessage, LogMessage, OpenFiles, OutputMessage, ScreenMessage.

Fortran Example:

 status = brm%WarningMessage("Parameter is out of range, using default")
 

MPI:

Called by root and (or) workers; only root writes to the log file.

Variable Documentation

bmi_failure

integer, parameter BMIPhreeqcRM::bmi_failure = 1

bmi_max_component_name

integer, parameter BMIPhreeqcRM::bmi_max_component_name = 2048

bmi_max_type_name

integer, parameter BMIPhreeqcRM::bmi_max_type_name = 2048

bmi_max_units_name

integer, parameter BMIPhreeqcRM::bmi_max_units_name = 2048

bmi_max_var_name

integer, parameter BMIPhreeqcRM::bmi_max_var_name = 2048

bmi_success

integer, parameter BMIPhreeqcRM::bmi_success = 0