mf6rtm.mup3d package

Submodules

mf6rtm.mup3d.base module

Base module of the mup3d package

class mf6rtm.mup3d.base.Block(data, ic=None)

Bases: object

Base class for PHREEQC input “keyword data blocks”.

Dictionary of geochemical components (keys) and their total concentrations (list) and other parameters, indexed by block number, similar to a .pqi file.

Type:: dict

names

List of names of geochemical components that serve as keys to the data.

Type:: list

ic

Initial condition.

Type:: array

eq_solutions

List of equilibrium solutions.

Type:: list

options

List of options.

Type:: list

get_names()

Get the names of geochemical components or phases specified in the block.

Returns:: List of names of geochemical components that serve as keys to the data.
Return type:: list

ic: None means no initial condition (-1)

set_equilibrate_solutions(eq_solutions)

Set the equilibrium solutions for the exchange phases. Array where index is the exchange phase number and value is the solution number to equilibrate with.

Parameters:: eq_solutions – List of equilibrium solution indices for each exchange phase.
Return type:: None

set_ic(ic)

Set the initial condition for the block.

Parameters:: ic (Union[int, float, ndarray]) – Initial condition concentrations. Can be an int, float, or ndarray.
Return type:: None

set_options(options)

Set the options for the block.

Parameters:: options – List of options for the block.
Return type:: None

class mf6rtm.mup3d.base.ChemStress(packnme)

Bases: object

The ChemStress class for handling stress period data.

packnme

Name of the package.

Type:: str

sol_spd

List of solution stress period data. Default is None.

Type:: list, optional

packtype

Type of the package. Default is None.

Type:: str, optional

set_packtype(packtype)

set_spd(sol_spd)

class mf6rtm.mup3d.base.EquilibriumPhases(data)

Bases: Block

The EquilibriumPhases Block.

parameters

Dictionary of parameters for the equilibrium phases. Default is None.

Type:: dict, optional

class mf6rtm.mup3d.base.ExchangePhases(data)

Bases: Block

The ExchangePhases Block.

parameters

Dictionary of parameters for the exchange phases. Default is None.

Type:: dict, optional

class mf6rtm.mup3d.base.GasPhase(data)

Bases: Block

The GasPhase Block.

parameters

Dictionary of parameters for the gas phase. Default is None.

Type:: dict, optional

class mf6rtm.mup3d.base.KineticPhases(data)

Bases: Block

The KineticPhases Block.

parameters

Dictionary of parameters for the kinetic phases. Default is None.

Type:: dict, optional

set_parameters(parameters)

class mf6rtm.mup3d.base.Mup3d(name=None, solutions=None, nlay=None, nrow=None, ncol=None, ncpl=None, nxyz=None)

Bases: object

The Mup3d class wrapper and extension for a PhreeqcRM model class.

This class extends the PhreeqcRM class to include additional methods that facilitate the coupling to Modflow6 via ModflowAPI.

name

Name of the model.

Type:: str

wd

Working directory path.

Type:: str

charge_offset

Charge offset, initialized to 0.0.

Type:: float

database

Path to the PHREEQC database file.

Type:: str

solutions

Solutions instance containing the geochemical data.

Type:: Solutions

init_temp

Initial temperature. Default is 25.0.

Type:: float, optional

equilibrium_phases

Equilibrium phases in the model.

Type:: EquilibriumPhases

kinetic_phases

Kinetic phases in the model.

Type:: KineticPhases

exchange_phases

Exchange phases in the model.

Type:: ExchangePhases

surfaces_phases

Surface phases in the model.

Type:: Surfaces

postfix

Postfix for the output files.

Type:: str

phreeqc_rm

PHREEQC reactive transport model instance.

Type:: object

init_conc_array_phreeqc

1D array of concentrations (mol/L) structured for PhreeqcRM, with each component concentration for each grid cell ordered by model.components.

Type:: ndarray

sconc

Dictionary of concentrations in units of moles per m^3 and structured to match the shape of Modflow’s grid.

Type:: dict[str, np.ndarray]

phinp

PHREEQC input instance.

Type:: object

components

List of chemical components.

Type:: list

fixed_components

List of fixed components.

Type:: list

nlay

Number of layers in the model grid.

Type:: int

nrow

Number of rows in the model grid.

Type:: int

ncol

Number of columns in the model grid.

Type:: int

nxyz

Total number of cells in the model grid, either (nlay * nrow * ncol) if DIS or (nlay * ncpl) if DISV or (nxyz) if DISU.

Type:: int

grid_shape

Shape of the model grid, either (nlay, nrow, ncol) if DIS or (nlay, ncpl) if DISV or (nxyz) if DISU.

Type:: tuple

generate_phreeqc_script(add_charge_flag=False)

Generates the phinp file for the MF6RTM model.

Parameters:: add_charge_flag (bool, optional) – Whether to add a charge flag to species in the solution block. Default is False.
Returns:: The generated PHREEQC script as a string.
Return type:: str

get_componenth2o()

Get componenth2o flag

Returns:: The value of the componenth2o flag.
Return type:: bool

get_config()

Retrieve config object

Returns:: Configuration parameters as a dictionary.
Return type:: dict

initialize(nthreads=1, add_charge_flag=False)

Initialize a PhreeqcRM object and calculate initial concentrations.

This method initializes a PhreeqcRM object using PHREEQC inputs and adds several key attributes to the Mup3d object for reactive transport modeling.

Parameters:

nthreads (int, optional) – Number of threads for parallel processing. Default is 1.
add_charge_flag (bool, optional) – Whether to add charge flag to species. Default is False.
Added (Attributes)
---------------
components (list) – List of transportable chemical components.
init_conc_array_phreeqc (ndarray) – 1D array of concentrations (mol/L) structured for PhreeqcRM, with each component concentration for each grid cell ordered by model.components.
sconc (dict) – Dictionary with components as keys and concentration arrays (mol/m^3) as values, structured to match the shape of the Modflow6 model domain grid.
phreeqc_rm (PhreeqcRM) – Initialized PhreeqcRM object.
nchem (int) – Number of chemistry cells.

Return type:

None

Notes

This method performs several key initialization steps: 1. Generates PHREEQC input script 2. Initializes PhreeqcRM object 3. Sets up initial conditions 4. Calculates initial concentrations 5. Converts concentrations to proper units and grid structure

initialize_chem_stress(attr, nthreads=1)

Initialize a PhreeqcRM object with boundary condition chemical concentrations for the specified Modflow Stress Period and Package.

Parameters:

attr (str) – The Modflow 6 Package name.
nthreads (int) – Number of threads to use for PhreeqcRM (default is 1).

Returns:

Dictionary with component names as keys and concentration arrays in moles/m3 as values.

Return type:

dict

Notes

This function initializes a PhreeqcRM object, loads a database, runs a Phreeqc input file, and transfers solutions and reactants to the reaction-module workers. It then equilibrates the cells, gets the concentrations, and converts them to moles/m3.

See also

phreeqcrm.PhreeqcRM: PhreeqcRM class documentation.

classmethod load_mup3d(filename='mup3d.pkl', wd='.')

Load a Mup3d object from a pickle file (class method). This creates a new Mup3d instance from a saved pickle file.

Parameters:

filename (str, optional) – Name of the pickle file. Default is ‘mup3d.pkl’.
working_dir (str, optional) – Directory containing the pickle file. Default is current directory.

Returns:

A new Mup3d instance loaded from the pickle file.

Return type:

Mup3d

Examples

>>> # Create a new model from pickle file
>>> model = Mup3d.load_mup3d('my_model.pkl', '/path/to/model/dir')

run(reactive=None, nthread=1, libname=None)

Wrapper function to run the MF6RTM model

Parameters:

reactive (bool, optional) –

Whether to run the model in reactive mode. If None, uses the value from the config nthread : int, optional

Number of threads to use for the simulation. Default is 1.

Returns:

True if the model ran successfully, False otherwise.

Return type:

bool

save_config()

Save config toml file

Returns:: Path to the saved configuration file.
Return type:: Path

save_mup3d(filename='mup3d.pkl')

Save the Mup3d object to a pickle file.

This method saves all non-private, non-callable attributes of the Mup3d object to a pickle file for later restoration using load_mup3d().

Parameters:: filename (str, optional) – Name of the pickle file. Default is ‘mup3d.pkl’.

set_charge_offset(charge_offset)

Sets the charge offset for the MF6RTM model to handle negative charge values

Parameters:: charge_offset (float) – The charge offset value to be added to the charge concentration.
Return type:: None

set_chem_stress(chem_stress)

Sets the ChemStress instance for the MF6RTM model.

Parameters:: chem_stress (ChemStress) – Instance of the ChemStress class containing stress period data.
Return type:: None

set_componenth2o(flag)

Set the component H2O to be True or False. if False Total H and Total O are transported if True H2O, Excess H and Excess O are transported

Parameters:: flag (bool) – True to include H2O as a component, False otherwise.
Returns:: The value of the componenth2o flag.
Return type:: bool
Raises:: AssertionError – If flag is not a boolean.

set_config(**kwargs)

Create and store a config object.

Parameters:: **kwargs (dict) – Configuration parameters for MF6RTMConfig.
Returns:: The created configuration object.
Return type:: MF6RTMConfig

set_database(database): Sets the database for the MF6RTM model.

Parameters:

database (str): The path to the database file.

Returns:

: None

set_equilibrium_phases(eq_phases)

Sets the equilibrium phases for the MF6RTM model.

Parameters:: eq_phases (EquilibriumPhases) – Instance of the EquilibriumPhases class containing geochemical data.
Return type:: None

set_exchange_phases(exchanger)

Sets the exchange phases for the MF6RTM model.

Parameters:: exchanger (ExchangePhases) – Instance of the ExchangePhases class containing geochemical data.
Return type:: None

set_fixed_components(fixed_components)

Set the fixed components for the MF6RTM model. These are the components that are not transported during the simulation.

Parameters:: fixed_components (list) – List of component names to be fixed (not transported).
Return type:: None

set_initial_temp(temp)

Sets the initial temperature for the MF6RTM model.

Parameters:: temp (int, float, or list) – Initial temperature value(s). Can be a single value (int or float) for homogeneous temperature or a list for spatially variable temperature.
Return type:: None

set_phases(phase)

Sets the phases for the MF6RTM model.

Parameters:: phase (KineticPhases, ExchangePhases, EquilibriumPhases, or Surfaces) – Instance of one of the phase classes containing geochemical data.
Return type:: None

set_postfix(postfix): Sets the postfix file for the MF6RTM model.

Parameters:

postfix (str): The path to the postfix file.

Returns:

: None

set_reaction_temp()

Sets the reaction temperature for the MF6RTM model.

Returns:: List of reaction temperatures for each grid cell.
Return type:: list

set_wd(wd)

Sets the working directory for the MF6RTM model.

Parameters:: (str) (wd)
Return type:: None
Raises:: AssertionError – If the working directory path is not a string.:

write_external_files_layered(internals=['exchange_phases', 'equilibrium_phases', 'kinetic_phases'], property_to_write=['m0'])

Write layered external text files for selected geochemical phases and properties.

For each specified geochemical phase (e.g., exchange, equilibrium, kinetic), this method extracts the given properties (e.g., ‘m0’) for all defined species and writes a separate file per layer in the simulation domain. The files are saved in the model’s working directory and follow the naming convention:

{phase}.{species}.{property}.layer{n}.txt

Parameters:

internals (list of str, optional) – List of model attributes containing geochemical phase data. Default is [“exchange_phases”, “equilibrium_phases”, “kinetic_phases”].
property_to_write (list of str, optional) – List of property names to extract and write per species and layer. Default is [‘m0’].

Return type:

None

write_internal_parameters(internals={'equilibrium_phases': ['si'], 'exchange_phases': ['dummy'], 'kinetic_phases': ['parms', 'formula', 'steps']})

Add non-external attributes to the config object.

Parameters:

internals (dict) –

Dictionary with phase names as keys and list of attributes to add as values. Default is {

”equilibrium_phases”: [“si”], “kinetic_phases”: [“parms”, “formula”, “steps”], “exchange_phases”: [“dummy”]

}.

Return type:

None

write_simulation()

Write phreqcrm simulation and configuration files

Return type:: None

class mf6rtm.mup3d.base.Solutions(data)

Bases: Block

The Solutions Block.

parameters

Dictionary of parameters for the solutions. Default is None.

Type:: dict, optional

class mf6rtm.mup3d.base.Surfaces(data)

Bases: Block

The Surfaces Block.

parameters

Dictionary of parameters for the surfaces. Default is None.

Type:: dict, optional

mf6rtm.mup3d.base.working_dir(path)

Context manager for changing the current working directory.

Parameters:: path (str) – Path to the directory to change to.
Yields:: None

Module contents

The mup3d module provides function to write input files for phreeqcrm and adds functionality to write files externally in a modflow-like fashion.

History: The Model Utility Preprocessor 3D (MUP3D) was envisioned by Mr. Beaker as a successort to PHT3D.

class mf6rtm.mup3d.Mup3d(name=None, solutions=None, nlay=None, nrow=None, ncol=None, ncpl=None, nxyz=None)

Bases: object

The Mup3d class wrapper and extension for a PhreeqcRM model class.

This class extends the PhreeqcRM class to include additional methods that facilitate the coupling to Modflow6 via ModflowAPI.

name

Name of the model.

Type:: str

wd

Working directory path.

Type:: str

charge_offset

Charge offset, initialized to 0.0.

Type:: float

database

Path to the PHREEQC database file.

Type:: str

solutions

Solutions instance containing the geochemical data.

Type:: Solutions

init_temp

Initial temperature. Default is 25.0.

Type:: float, optional

equilibrium_phases

Equilibrium phases in the model.

Type:: EquilibriumPhases

kinetic_phases

Kinetic phases in the model.

Type:: KineticPhases

exchange_phases

Exchange phases in the model.

Type:: ExchangePhases

surfaces_phases

Surface phases in the model.

Type:: Surfaces

postfix

Postfix for the output files.

Type:: str

phreeqc_rm

PHREEQC reactive transport model instance.

Type:: object

init_conc_array_phreeqc

1D array of concentrations (mol/L) structured for PhreeqcRM, with each component concentration for each grid cell ordered by model.components.

Type:: ndarray

sconc

Dictionary of concentrations in units of moles per m^3 and structured to match the shape of Modflow’s grid.

Type:: dict[str, np.ndarray]

phinp

PHREEQC input instance.

Type:: object

components

List of chemical components.

Type:: list

fixed_components

List of fixed components.

Type:: list

nlay

Number of layers in the model grid.

Type:: int

nrow

Number of rows in the model grid.

Type:: int

ncol

Number of columns in the model grid.

Type:: int

nxyz

Total number of cells in the model grid, either (nlay * nrow * ncol) if DIS or (nlay * ncpl) if DISV or (nxyz) if DISU.

Type:: int

grid_shape

Shape of the model grid, either (nlay, nrow, ncol) if DIS or (nlay, ncpl) if DISV or (nxyz) if DISU.

Type:: tuple

generate_phreeqc_script(add_charge_flag=False)

Generates the phinp file for the MF6RTM model.

Parameters:: add_charge_flag (bool, optional) – Whether to add a charge flag to species in the solution block. Default is False.
Returns:: The generated PHREEQC script as a string.
Return type:: str

get_componenth2o()

Get componenth2o flag

Returns:: The value of the componenth2o flag.
Return type:: bool

get_config()

Retrieve config object

Returns:: Configuration parameters as a dictionary.
Return type:: dict

initialize(nthreads=1, add_charge_flag=False)

Initialize a PhreeqcRM object and calculate initial concentrations.

This method initializes a PhreeqcRM object using PHREEQC inputs and adds several key attributes to the Mup3d object for reactive transport modeling.

Parameters:

nthreads (int, optional) – Number of threads for parallel processing. Default is 1.
add_charge_flag (bool, optional) – Whether to add charge flag to species. Default is False.
Added (Attributes)
---------------
components (list) – List of transportable chemical components.
init_conc_array_phreeqc (ndarray) – 1D array of concentrations (mol/L) structured for PhreeqcRM, with each component concentration for each grid cell ordered by model.components.
sconc (dict) – Dictionary with components as keys and concentration arrays (mol/m^3) as values, structured to match the shape of the Modflow6 model domain grid.
phreeqc_rm (PhreeqcRM) – Initialized PhreeqcRM object.
nchem (int) – Number of chemistry cells.

Return type:

None

Notes

This method performs several key initialization steps: 1. Generates PHREEQC input script 2. Initializes PhreeqcRM object 3. Sets up initial conditions 4. Calculates initial concentrations 5. Converts concentrations to proper units and grid structure

initialize_chem_stress(attr, nthreads=1)

Initialize a PhreeqcRM object with boundary condition chemical concentrations for the specified Modflow Stress Period and Package.

Parameters:

attr (str) – The Modflow 6 Package name.
nthreads (int) – Number of threads to use for PhreeqcRM (default is 1).

Returns:

Dictionary with component names as keys and concentration arrays in moles/m3 as values.

Return type:

dict

Notes

This function initializes a PhreeqcRM object, loads a database, runs a Phreeqc input file, and transfers solutions and reactants to the reaction-module workers. It then equilibrates the cells, gets the concentrations, and converts them to moles/m3.

See also

phreeqcrm.PhreeqcRM: PhreeqcRM class documentation.

classmethod load_mup3d(filename='mup3d.pkl', wd='.')

Load a Mup3d object from a pickle file (class method). This creates a new Mup3d instance from a saved pickle file.

Parameters:

filename (str, optional) – Name of the pickle file. Default is ‘mup3d.pkl’.
working_dir (str, optional) – Directory containing the pickle file. Default is current directory.

Returns:

A new Mup3d instance loaded from the pickle file.

Return type:

Mup3d

Examples

>>> # Create a new model from pickle file
>>> model = Mup3d.load_mup3d('my_model.pkl', '/path/to/model/dir')

run(reactive=None, nthread=1, libname=None)

Wrapper function to run the MF6RTM model

Parameters:

reactive (bool, optional) –

Whether to run the model in reactive mode. If None, uses the value from the config nthread : int, optional

Number of threads to use for the simulation. Default is 1.

Returns:

True if the model ran successfully, False otherwise.

Return type:

bool

save_config()

Save config toml file

Returns:: Path to the saved configuration file.
Return type:: Path

save_mup3d(filename='mup3d.pkl')

Save the Mup3d object to a pickle file.

This method saves all non-private, non-callable attributes of the Mup3d object to a pickle file for later restoration using load_mup3d().

Parameters:: filename (str, optional) – Name of the pickle file. Default is ‘mup3d.pkl’.

set_charge_offset(charge_offset)

Sets the charge offset for the MF6RTM model to handle negative charge values

Parameters:: charge_offset (float) – The charge offset value to be added to the charge concentration.
Return type:: None

set_chem_stress(chem_stress)

Sets the ChemStress instance for the MF6RTM model.

Parameters:: chem_stress (ChemStress) – Instance of the ChemStress class containing stress period data.
Return type:: None

set_componenth2o(flag)

Set the component H2O to be True or False. if False Total H and Total O are transported if True H2O, Excess H and Excess O are transported

Parameters:: flag (bool) – True to include H2O as a component, False otherwise.
Returns:: The value of the componenth2o flag.
Return type:: bool
Raises:: AssertionError – If flag is not a boolean.

set_config(**kwargs)

Create and store a config object.

Parameters:: **kwargs (dict) – Configuration parameters for MF6RTMConfig.
Returns:: The created configuration object.
Return type:: MF6RTMConfig

set_database(database): Sets the database for the MF6RTM model.

Parameters:

database (str): The path to the database file.

Returns:

: None

set_equilibrium_phases(eq_phases)

Sets the equilibrium phases for the MF6RTM model.

Parameters:: eq_phases (EquilibriumPhases) – Instance of the EquilibriumPhases class containing geochemical data.
Return type:: None

set_exchange_phases(exchanger)

Sets the exchange phases for the MF6RTM model.

Parameters:: exchanger (ExchangePhases) – Instance of the ExchangePhases class containing geochemical data.
Return type:: None

set_fixed_components(fixed_components)

Set the fixed components for the MF6RTM model. These are the components that are not transported during the simulation.

Parameters:: fixed_components (list) – List of component names to be fixed (not transported).
Return type:: None

set_initial_temp(temp)

Sets the initial temperature for the MF6RTM model.

Parameters:: temp (int, float, or list) – Initial temperature value(s). Can be a single value (int or float) for homogeneous temperature or a list for spatially variable temperature.
Return type:: None

set_phases(phase)

Sets the phases for the MF6RTM model.

Parameters:: phase (KineticPhases, ExchangePhases, EquilibriumPhases, or Surfaces) – Instance of one of the phase classes containing geochemical data.
Return type:: None

set_postfix(postfix): Sets the postfix file for the MF6RTM model.

Parameters:

postfix (str): The path to the postfix file.

Returns:

: None

set_reaction_temp()

Sets the reaction temperature for the MF6RTM model.

Returns:: List of reaction temperatures for each grid cell.
Return type:: list

set_wd(wd)

Sets the working directory for the MF6RTM model.

Parameters:: (str) (wd)
Return type:: None
Raises:: AssertionError – If the working directory path is not a string.:

write_external_files_layered(internals=['exchange_phases', 'equilibrium_phases', 'kinetic_phases'], property_to_write=['m0'])

Write layered external text files for selected geochemical phases and properties.

For each specified geochemical phase (e.g., exchange, equilibrium, kinetic), this method extracts the given properties (e.g., ‘m0’) for all defined species and writes a separate file per layer in the simulation domain. The files are saved in the model’s working directory and follow the naming convention:

{phase}.{species}.{property}.layer{n}.txt

Parameters:

internals (list of str, optional) – List of model attributes containing geochemical phase data. Default is [“exchange_phases”, “equilibrium_phases”, “kinetic_phases”].
property_to_write (list of str, optional) – List of property names to extract and write per species and layer. Default is [‘m0’].

Return type:

None

write_internal_parameters(internals={'equilibrium_phases': ['si'], 'exchange_phases': ['dummy'], 'kinetic_phases': ['parms', 'formula', 'steps']})

Add non-external attributes to the config object.

Parameters:

internals (dict) –

Dictionary with phase names as keys and list of attributes to add as values. Default is {

”equilibrium_phases”: [“si”], “kinetic_phases”: [“parms”, “formula”, “steps”], “exchange_phases”: [“dummy”]

}.

Return type:

None

write_simulation()

Write phreqcrm simulation and configuration files

Return type:: None

mf6rtm.mup3d package

Submodules

mf6rtm.mup3d.base module

Parameters:

Returns:

Parameters:

Returns:

Module contents

Parameters:

Returns:

Parameters:

Returns: