Naming and Type conventions

Setup list

The setup list holds all values, which can be parsed by poet. It's divided into components of POET e.g. chemistry, diffusion etc. and hold metadata information like timestep of each iteration, count of iterations etc.

# Define a setup list for simulation configuration
list(
    Grid = list(),                    # Parameters related to the grid structure
    Diffusion = list(),               # Parameters related to diffusion processes
    Advection = list(),               # Parameters related to advection processes (Work in progress)
    Chemistry = list()               # Parameters related to chemical processes
)

Grid (Geometry)

x equals to the horizontal axis, y to the vertical axis.

# Define grid configuration for POET model
Grid <- list(
    pqc_in_file = character(),          # Path to the input script for Phreeqc
    #OR
    pqc_in_string = character(),        # Phreeqc input script as string
    #---#
    pqc_with_redox = logical(),         # optional: Whether to use redox states of solutions in Phreeqc. Default is FALSE.
    pqc_with_h0_o0 = logical(),         # optional: Whether to use H(0) and O(0) in Phreeqc. Default is FALSE.
    #---#
    pqc_db_file = character(),          # Path to the database file for Phreeqc
    #OR
    pqc_db_string = character(),        # Phreeqc database file as string
    #---#
    grid_def = matrix(),                # Definition of the grid, containing IDs according to the Phreeqc input script
    grid_size = numeric(),              # Size of the grid in meters (x,y)
    constant_cells = numeric(),         # IDs of cells with constant concentration (PLACEHOLDER)
    porosity = numeric(nrow * ncol) | numeric(1), # Porosity of the grid (PLACEHOLDER)
)

Diffusion

As the current code refactoring is still in progress, the diffusion setup is focused on 2D grids. There is no support for 1D grids right now, but can be implemented in the future quite easily.

Diffusion <- list(
    boundaries = list(                  # Define boundary conditions for diffusion
        "N" = list(
            "type" = character(),       # Define the type of boundary (e.g. "fixed_grad", "closed", "constant")
            "cell" = numeric(),         # Define the cell ID; counting begins @ 1 (N/W beginning on the left side to the right, E/S on the upper side downwards)
            "sol_id" = numeric(),       # Define the Phreeqc solution ID for the boundary
        ),
        # Only those boundaries needs to be defined, which are not "closed" 
        "E" = list(...),                
        # You can also leave sides out -> closed boundary on complete side
    ),
    inner_boundaries = list(            # define inner constant boundaries for diffusion
        "row" = numeric(),              # Define the row ID; counting begins @ 1
        "col" = numeric(),              # Define the column ID; counting begins @ 1
        "sol_id" = numeric()            # Define the Phreeqc solution ID for the boundary
    ),
    # alphas can be set by a list of matrices for ALL species to transport
    alpha_x = list(                      
        "element1" = numeric(nrow * ncol), # column-major order
        # OR
        "element2" = numeric(1), # for homogenous diffusion coefficients
        ...
    ), 
    # or by defining a single matrix for all species, assuming homogenous diffusion coefficients among species at the same cell index
    alpha_x = numeric(nrow * ncol), # column-major order
    # or by defining a single value, which acts as a homogeneous diffusion coefficient for all species and cells
    alpha_x = numeric(1),
    # ---- 
    alpha_y = alpha_x # See annotations for alphax
)

Chemistry

I think we need to refactor the list of inputs. Maybe we should move the hook functions into a separate input file and evaluete them at runtime.

Instead of preprocessing them and write them to the simulation initialization file, my suggestion is to output a template file after initialization, defining all species and allowing the user to adjust significant digits for DHT and Interpolation keys. This file can, when not edited in its definings etc, be read by POET without any problems.

For the hook functions, I don't have a good idea right now.

Chemistry <- list(
    dht_species = numeric(),           # optional: Named vector with species to use with significant digits for DHT key rounding
    pht_species = numeric(),           # optional: Named vector with species to use with significant digits for Interpolation key rounding
    hooks = list(                      # optional: List of hooks to run before and after certain steps
        dht_fill = logical() <- function(numeric(), numeric()), # function to run before writing DHT
        dht_fuzz = numeric() <- function(numeric()),            # function to run before reading DHT 
        interp_pre = numeric() <- function(numeric(), list()), # function to run before interpolation
        interp_post = logical() <- function(numeric())      # function to run after interpolation
    )
)

Runtime parameters

Runtime <- list(
    timesteps = numeric(iterations),   # Time step size for each iteration
    store_result = TRUE,               # Whether to store simulation results
    out_save = numeric()               # Optional: Iterations to save simulation results
)