cs_gwf_tracer.h

Go to the documentation of this file.

#ifndef CS_GWF_TRACER_H
#define CS_GWF_TRACER_H
 
/*============================================================================
 * Set of main functions to handle soils in the groundwater flow module
 * when using CDO schemes
 *============================================================================*/
 
/*
  This file is part of code_saturne, a general-purpose CFD tool.
 
  Copyright (C) 1998-2026 EDF S.A.
 
  This program is free software; you can redistribute it and/or modify it under
  the terms of the GNU General Public License as published by the Free Software
  Foundation; either version 2 of the License, or (at your option) any later
  version.
 
  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  details.
 
  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
  Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
 
/*----------------------------------------------------------------------------*/
 
/*----------------------------------------------------------------------------
 *  Local headers
 *----------------------------------------------------------------------------*/
 
#include "cdo/cs_advection_field.h"
#include "base/cs_base.h"
#include "cdo/cs_equation.h"
#include "gwf/cs_gwf_param.h"
 
/*============================================================================
 * Typedef definition
 *============================================================================*/
 
typedef struct _gwf_tracer_t  cs_gwf_tracer_t;
 
/* \struct cs_gwf_tracer_default_context_t
 *
 * \brief Set of parameters related to a tracer equation attached to a standard
 *        modelling
 */
 
typedef struct _gwf_tracer_default_context_t  cs_gwf_tracer_default_context_t;
 
/*============================================================================
 * Public function pointer prototypes
 *============================================================================*/
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
typedef void
(cs_gwf_tracer_init_setup_t) (cs_gwf_tracer_t             *tracer);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
typedef void
(cs_gwf_tracer_finalize_setup_t) (const cs_cdo_connect_t      *connect,
                                  const cs_cdo_quantities_t   *quant,
                                  const cs_adv_field_t        *adv,
                                  cs_gwf_tracer_t             *tracer);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
typedef void
(cs_gwf_tracer_update_t) (cs_gwf_tracer_t             *tracer,
                          void                        *context,
                          const cs_time_step_t        *ts,
                          const cs_mesh_t             *mesh,
                          const cs_cdo_connect_t      *connect,
                          const cs_cdo_quantities_t   *quant);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
typedef void
(cs_gwf_tracer_free_context_t) (cs_gwf_tracer_t      *tracer);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
typedef void
(cs_gwf_tracer_integrate_t)(const cs_cdo_connect_t          *connect,
                            const cs_cdo_quantities_t       *cdoq,
                            const cs_equation_t             *eq,
                            const cs_zone_t                 *zone,
                            void                            *context,
                            double                           results[]);
 
/*============================================================================
 * Structure definitions
 *============================================================================*/
 
/* Structure to handle of radioactive decay chain  */
 
typedef struct {
 
  char                  *name;       /* Name of the decay chain */
  int                    id;         /* Position in the array of chain decays */
 
  int                    n_tracers;  /* Number of tracers in the decay chain */
  cs_gwf_tracer_unit_t   unit;       /* Type of unit measure:
                                      *  - mole (classical tracer)
                                      *  - Becquerel (activity)
                                      */
 
  cs_gwf_tracer_t      **tracers;   /* Array of tracers associated to the
                                       decay chain. tracers[0] is the parent
                                       without any ancestor. */
 
  cs_xdef_t            **st_defs;   /* List of source term definitions */
 
} cs_gwf_tracer_decay_chain_t;
 
/* Set of parameters related to a tracer equation attached to a standard
   modelling */
 
struct _gwf_tracer_default_context_t {
 
  /* Common settings shared by all physical modelling */
  /* ------------------------------------------------ */
 
  double     decay_coef;   /* First order decay coefficient (related to the
                              reaction term). This value is intrinsic to the
                              component (a radioactive element for instance)
                              and not to the soil. */
 
  /* The following parameters are defined for each soil (arrays of size equal
   * to n_soils) */
 
  double    *rho_bulk;      /* bulk density (kg.m^-3) */
  double    *kd0;           /* reference value of the distribution coefficient
                               (m^".kg^-1) */
  double    *rho_kd;        /* Derived quantity: rho_bulk*kd0 */
 
  double    *alpha_l;       /* Longitudinal dispersivity */
  double    *alpha_t;       /* Transversal dispersivity */
 
  double    *wmd;           /* Water molecular diffusivity (m^2.s^-1) */
 
  /* Precipitation members (set to null if not used) */
  /* ----------------------------------------------- */
 
  double       *conc_l_star;    /* maximal value of the concentration of
                                 * tracer in the liquid phase in mol/m^3. There
                                 * is one user-defined value for each soil. The
                                 * exceeded quantities are stored in the solid
                                 * phase (-> precip_mass). These values
                                 * corresponds to the user settings
                                 */
 
  cs_real_t    *precip_mass;    /* array storing the mass of precipitate
                                 * (solid) in the dedicated auxiliary
                                 * storage. The size of this array may vary
                                 * w.r.t. to the discretization scheme.
                                 */
 
  cs_field_t   *precip_field;   /* field structure storing the (interpolated)
                                 * values of the concentration of precipitate
                                 * in mol/kg in each cell.
                                 */
 
  /* Sorption members (set to null if not used) */
  /* ------------------------------------------ */
 
  double       *k0_plus;        /* kinetic coefficient towards site 2 locations
                                   (m^3.kg^-1.s^-1) */
  double       *k0_minus;       /* kinetic coefficient from site 2 locations
                                   (s^-1) */
 
  cs_real_t    *conc_site2;     /* array allocated to n_cells whatever the
                                   space discretization is */
 
  /* Variables used for the update of physical properties (shared pointers) */
 
  const cs_field_t    *darcy_velocity_field;
 
};
 
/* Set of parameters describing a tracer structure */
/* ----------------------------------------------- */
 
struct _gwf_tracer_t {
 
  cs_gwf_model_type_t     hydraulic_model;
 
  cs_gwf_tracer_model_t   model;
 
  cs_field_t             *diffusivity;
 
  int                     reaction_id;
 
  cs_equation_t          *equation;
 
  void                   *context;
 
  int                     chain_position_id;
 
  int                     chain_id;
 
  cs_gwf_tracer_update_t           *update_diff_pty;
  cs_gwf_tracer_update_t           *update_precipitation;
  cs_gwf_tracer_update_t           *update_decay_chain_st;
 
  cs_gwf_tracer_integrate_t        *integrate;
 
  cs_gwf_tracer_init_setup_t       *init_setup;
  cs_gwf_tracer_finalize_setup_t   *finalize_setup;
  cs_gwf_tracer_free_context_t     *free_context;
 
};
 
/*============================================================================
 * Public function prototypes
 *============================================================================*/
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_gwf_tracer_t *
cs_gwf_tracer_by_name(const char   *eq_name);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_gwf_tracer_t *
cs_gwf_tracer_add(cs_gwf_tracer_model_t            tr_model,
                  cs_gwf_model_type_t              gwf_model,
                  const char                      *eq_name,
                  const char                      *var_name,
                  cs_adv_field_t                  *adv_field,
                  double                           lambda,
                  int                              chain_position,
                  int                              chain_id,
                  cs_gwf_tracer_init_setup_t      *init_setup,
                  cs_gwf_tracer_finalize_setup_t  *finalize_setup);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_free_all(void);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_real_t
cs_gwf_tracer_get_time_theta_max(void);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_set_soil_param(cs_gwf_tracer_t   *tracer,
                             const char        *soil_name,
                             double             wmd,
                             double             alpha_l,
                             double             alpha_t,
                             double             distrib_coef);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_set_precip_param(cs_gwf_tracer_t   *tracer,
                               const char        *soil_name,
                               double             conc_l_star);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_init_setup(void);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_finalize_setup(const cs_cdo_connect_t      *connect,
                             const cs_cdo_quantities_t   *quant);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_update_diff_pty(const cs_time_step_t        *ts,
                              const cs_mesh_t             *mesh,
                              const cs_cdo_connect_t      *connect,
                              const cs_cdo_quantities_t   *quant);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_log_all(void);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_compute_steady_all(const cs_mesh_t              *mesh,
                                 const cs_time_step_t         *time_step,
                                 const cs_cdo_connect_t       *connect,
                                 const cs_cdo_quantities_t    *cdoq);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_compute_all(const cs_mesh_t              *mesh,
                          const cs_time_step_t         *time_step,
                          const cs_cdo_connect_t       *connect,
                          const cs_cdo_quantities_t    *cdoq);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_default_init_setup(cs_gwf_tracer_t     *tracer);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_sat_finalize_setup(const cs_cdo_connect_t      *connect,
                                 const cs_cdo_quantities_t   *quant,
                                 const cs_adv_field_t        *adv,
                                 cs_gwf_tracer_t             *tracer);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_unsat_finalize_setup(const cs_cdo_connect_t      *connect,
                                   const cs_cdo_quantities_t   *quant,
                                   const cs_adv_field_t        *adv,
                                   cs_gwf_tracer_t             *tracer);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
double
cs_gwf_tracer_integrate(const cs_cdo_connect_t     *connect,
                        const cs_cdo_quantities_t  *cdoq,
                        const cs_gwf_tracer_t      *tracer,
                        const char                 *z_name);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_gwf_tracer_integrate_by_terms(const cs_cdo_connect_t     *connect,
                                 const cs_cdo_quantities_t  *cdoq,
                                 const cs_gwf_tracer_t      *tracer,
                                 const char                 *z_name,
                                 double                      results[]);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_gwf_tracer_decay_chain_t *
cs_gwf_tracer_create_decay_chain(int                      n_tracers,
                                 const char              *chain_name,
                                 cs_gwf_tracer_unit_t     unit);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_gwf_tracer_decay_chain_t *
cs_gwf_tracer_decay_chain_by_id(int        id);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_gwf_tracer_decay_chain_t *
cs_gwf_tracer_decay_chain_by_name(const char      *chain_name);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_gwf_tracer_t *
cs_gwf_tracer_decay_chain_get_tracer(cs_gwf_tracer_decay_chain_t  *tdc,
                                     int                           id);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_equation_t *
cs_gwf_tracer_decay_chain_get_equation(cs_gwf_tracer_decay_chain_t  *tdc,
                                       int                           id);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_equation_param_t *
cs_gwf_tracer_decay_chain_get_equation_param(cs_gwf_tracer_decay_chain_t  *tdc,
                                             int                           id);
 
/*----------------------------------------------------------------------------*/
 
#endif /* CS_GWF_TRACER_H */