Package ummisco.gama.chemmisol

Class ChemicalSystem

java.lang.Object
ummisco.gama.chemmisol.ChemicalSystem
All Implemented Interfaces:
AutoCloseable
public class ChemicalSystem extends Object implements AutoCloseable
Describes a chemical system, where components reacts to form other chemical species according to chemical reactions.

This class is responsible for most of the native calls to the chemmisol-cpp library.

In order to guarantee a proper release of the C++ memory resources, ChemicalSystem implements the AutoClosable interface so that it can be used in a try-with-resources block: 

 try(ChemicalSystem system = new ChemicalSystem()) {
        ...
 }
All quantities must currently be specified in core units of the chemmisol unit system.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    ChemicalSystem.ChemmisolCoreException
    Wrapper around exceptions thrown by the native chemmisol-cpp library.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ChemicalSystem()
    Initializes a default chemical system.
    ChemicalSystem(double solid_concentration, double specific_surface_area, double site_concentration)
    Initializes a mineral chemical system.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addComponent(ChemicalComponent component)
    Adds a component to this chemical system.
    void
    addReaction(Reaction reaction)
    Adds a new reaction to the chemical system.
    void
    addSpecies(ChemicalSpecies species)
    Adds a species to this chemical system.
    void
    close()
     
    double
    concentration(String species_name)
    Gets the concentration of the species with the specified name directly from the native chemmisol-cpp library.
    protected void
    dispose()
    Releases C++ memory resources used by this ChemicalSystem instance.
    void
    fixPH(double ph)
    Fixes the pH in a default component named "H+".
    void
    fixPH(double ph, ChemicalComponent h_component)
    Fixes the pH, using the provided component as the chemical component representing the H+ ions.
    double
    reactionQuotient(String reaction_name)
    Returns the reaction quotient of the reaction named reaction_name in this chemical system.
    double
    reactionQuotient(Reaction reaction)
    Returns the reaction quotient of the specified reaction.
    void
    setTotalConcentration(ChemicalComponent component, double total_concentration)
    Sets the total concentration of the provided component.
    void
    setUp()
    Sets up the system so that it is ready to be solved.
    double
    sitesQuantity()
    Returns the total quantity of sites of the surface complex, computed from the solid_concentration, specific_surface_area and site_concentration parameters specified in the ChemicalSystem definition.
    void
    solve()
    Solves the equilibrium state of this chemical system using the native chemmisol-cpp solver.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • ChemicalSystem

      public ChemicalSystem()
      Initializes a default chemical system.

    • ChemicalSystem

      public ChemicalSystem(double solid_concentration, double specific_surface_area, double site_concentration)
      Initializes a mineral chemical system. Example units are provided for each parameter for a better understanding, but values must at least be specified so that the value of solid_concentration * specific_surface_area * site_concentration is expressed in mol/l. The simplest way is to only use chemmisol core units, i.e. g/l, m2/g and mol/m2.
      Parameters:
      solid_concentration - Mass concentration of mineral in suspension in the solution, expressed in g/l.
      specific_surface_area - Surface of the solid in contact with the solution per unit of mass, usually expressed in m2/g.
      site_concentration - Quantity of sites per unit of surface in contact with the solution, usually expressed as entities/nm2.

  • Method Details

    • addReaction

      public void addReaction(Reaction reaction)
      Adds a new reaction to the chemical system.

      Each reaction must have a unique name within this chemical system.

      It is the responsability of the user to properly define reactions and components so that reagents of the reaction all correspond to chemical components, except the produced species (see Reaction).

      For a reaction to be valid, components only need to be defined when setUp() is called.

      Parameters:
      reaction - Reaction to add to this chemical system.

    • addComponent

      public void addComponent(ChemicalComponent component) throws ChemicalSystem.ChemmisolCoreException
      Adds a component to this chemical system.

      Components are canonical components used to specify reactions. The species associated to the component is automatically added to this chemical system.

      Parameters:
      component - Component to add to this chemical system.
      Throws:
      ChemicalSystem.ChemmisolCoreException - if an exception occurs while setting up the chemical system in the native chemmisol-cpp library.
      See Also:

    • addSpecies

      public void addSpecies(ChemicalSpecies species)
      Adds a species to this chemical system.

      Any concentration change resulting from the equilibrium solving is automatically reported in the provided ChemicalSpecies instance. The concentration of species not added with addSpecies() can still be queried using the concentration(java.lang.String) method.

      Parameters:
      species - Species to add to this chemical system.
      See Also:

    • fixPH

      public void fixPH(double ph, ChemicalComponent h_component)
      Fixes the pH, using the provided component as the chemical component representing the H+ ions.

      The concentration of the associated component is set to 10^-pH.

      Parameters:
      ph - pH value.
      h_component - Chemical component instance representing the H+ ions.

    • fixPH

      public void fixPH(double ph)
      Fixes the pH in a default component named "H+".

      If a species name H+ is already defined in the chemical system, this species is used as the species representing H+ ions. Else, the pH value is only set internally in the chemmisol-cpp library, but can be queried with concentration("H+").

      Parameters:
      ph - pH value

    • setTotalConcentration

      public void setTotalConcentration(ChemicalComponent component, double total_concentration)
      Sets the total concentration of the provided component.

      This updates the value returned by ChemicalComponent#getTotalConcentration(), and sets the total concentration of the component within the internal chemmisol-cpp solver instance. The total concentration must be expressed in mol/l for aqueous species, and as a molar fraction (without unit) for mineral species.

      Parameters:
      component - Chemical component to set with the specified total concentration.
      total_concentration - Total concentration of the chemical component.

    • setUp

      public void setUp() throws ChemicalSystem.ChemmisolCoreException
      Sets up the system so that it is ready to be solved.

      This method must be called before solve() once all reactions and components have been added, and each time the total concentration of a component is updated.

      Throws:
      ChemicalSystem.ChemmisolCoreException - if an exception occurs while setting up the chemical system in the native chemmisol-cpp library.
      See Also:

    • solve

      public void solve() throws ChemicalSystem.ChemmisolCoreException
      Solves the equilibrium state of this chemical system using the native chemmisol-cpp solver.

      The concentration of all species added explicitly with addSpecies() or implicitly with addComponent() are updated according to the solved equilibrium state, and is available using the concentration(java.lang.String) method.

      Throws:
      ChemicalSystem.ChemmisolCoreException - if an exception occurs within the native chemmisol-cpp solver.

    • concentration

      public double concentration(String species_name)
      Gets the concentration of the species with the specified name directly from the native chemmisol-cpp library.

      This method might be useful to retrieve the concentration of a species that exists in the system but not added explicitly with addSpecies() or implicitly with addComponent().

      Parameters:
      species_name - Name of a chemical species.
      Returns:
      Internal concentration of the species named species_name.

    • reactionQuotient

      public double reactionQuotient(Reaction reaction)
      Returns the reaction quotient of the specified reaction.

      The reaction must have been added to the system with addReaction(ummisco.gama.chemmisol.Reaction).

      For a reaction defined as 

           n A + m B <-> k C + l D
      the reaction quotient is computed as 
          Q = ([C]^k * [D]^l) / ([A]^n * [B]^m)
      Parameters:
      reaction - Reaction instance within this chemical system.
      Returns:
      Reaction quotient of the reaction.

    • reactionQuotient

      public double reactionQuotient(String reaction_name)
      Returns the reaction quotient of the reaction named reaction_name in this chemical system.

      A reaction with the specified name must have been added to the system with addReaction(ummisco.gama.chemmisol.Reaction).

      Parameters:
      reaction_name - Name of a reaction in this chemical system.
      Returns:
      Reaction quotient of the reaction.
      See Also:

    • sitesQuantity

      public double sitesQuantity()
      Returns the total quantity of sites of the surface complex, computed from the solid_concentration, specific_surface_area and site_concentration parameters specified in the ChemicalSystem definition. If those parameters were not provided, the quantity of sites is null.
      Returns:
      Total quantity of sites in the chemical system.

    • dispose

      protected void dispose()
      Releases C++ memory resources used by this ChemicalSystem instance.

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable