add docs, allow passing salt pairs to ISElecrolyteWrapper

Author: longemen3000

docs/src/eos/electrolytes.md

@@ -8,10 +8,23 @@ CurrentModule = Clapeyron
 Pages = ["electrolytes.md"]
 ```
 
-## Main model
+## Explicit vs. Implicit Solvent Models
+
+Electrolyte equations of state model mixtures containing charged species (ions). For such a mixture to be in thermodynamic equilibrium, a fundamental constraint must be imposed: the total electrical charge must sum to zero. This is the condition of **electroneutrality**.
+
+How a model handles charged species defines its approach:
+
+- **Explicit Solvent Models:** These models work directly with individual ions as components (e.g., Na⁺, Cl⁻). While conceptually straightforward at the model level—ions are uniquely defined—performing phase equilibrium calculations requires explicitly satisfying the electroneutrality constraint alongside all other equilibrium conditions (like equality of chemical potentials). This adds a layer of complexity to equilibrium calculations.
+
+- **Implicit Solvent Models:** To circumvent the complexity of the electroneutrality constraint, this approach groups ions into electrically neutral pairs, representing them as a single **salt component** (e.g., NaCl). The remaining components (like water) are implicitly treated as the solvent for these salts. Consequently, models that work with salt components are known as implicit solvent models.
+
+In Clapeyron.jl, our primary implementation uses the **explicit solvent** approach. However, to provide flexibility and connect the two methodologies, we offer the `ISElectrolyteWrapper`, which can transform an explicit solvent model into an equivalent implicit solvent representation.
+
+## Main models
 
 ```@docs
 Clapeyron.ESElectrolyte
+Clapeyron.ISElectrolyteWrapper
 ```
 
 ## Ion Models
@@ -41,4 +54,4 @@ Clapeyron.ConstRSP
 Clapeyron.LinMixRSP
 Clapeyron.Schreckenberg
 Clapeyron.ZuoFurst
-```
+```

docs/src/properties/electrolytes.md

@@ -28,4 +28,4 @@ Clapeyron.molality_to_composition
 
 ```@docs
 Clapeyron.dielectric_constant
-```
+```

src/methods/property_solvers/stability/tpd.jl

@@ -383,7 +383,6 @@ function tpd_plan(model,z,is_liquidz,lle,id_test,K_test,pure_test)
         end
     end
 
-
     return plan
 end
 

src/models/Electrolytes/ISElectrolyte.jl

@@ -1,15 +1,30 @@
-
-
-
-struct ISElectrolite{T<:IdealModel,c<:EoSModel,i<:IonModel} <: ISElectrolyteModel
-    components::Array{String,1}
-    idealmodel::T
-    neutralmodel::c
-    ionmodel::i
-    references::Array{String,1}
-end
-
-
+"""
+    ISElectrolyteWrapper(model::ESElectrolyteModel;salts = nothing)
+
+
+Given en explicit solvent model, returns an implicit solvent model, where are the charged components are paired to form binary salts.
+If no `salts` argument is specified, the salt pairings will be created via [`Clapeyron.auto_binary_salts`](@ref).
+## Example
+
+´´´julia-repl
+julia> system = ePCSAFT(["water","acetonitrile"],["sodium","chloride"])
+Explicit Electrolyte Model with 4 components:
+ "water"
+ "acetonitrile"
+ "sodium" (+1)
+ "chloride" (-1)
+Neutral Model: pharmaPCSAFT{BasicIdeal, Float64}
+Ion Model: hsdDH{ConstRSP}
+RSP Model: ConstRSP
+
+julia> salt_system = ISElectrolyteWrapper(system)
+ISElectrolyteWrapper{ePCSAFT{BasicIdeal, pharmaPCSAFT{BasicIdeal, Float64}, hsdDH{ConstRSP}}} with 3 components:
+ "water"
+ "acetonitrile"
+ "sodium.chloride"
+´´´
+
+"""
 struct ISElectrolyteWrapper{M} <: ISElectrolyteModel
     components::Vector{String}
     model::M
@@ -22,8 +37,8 @@ struct ISElectrolyteIdealWrapper{M} <: IdealModel
     salt::SaltParam
 end
 
-function ISElectrolyteWrapper(model::ESElectrolyteModel)
-    salt = SaltParam(model)
+function ISElectrolyteWrapper(model::ESElectrolyteModel;salts = nothing)
+    salt = SaltParam(model,salts)
     components = salt.implicit_components
     return ISElectrolyteWrapper(components,model,salt)
 end

src/models/Electrolytes/SaltParam.jl

@@ -49,10 +49,16 @@ function explicit_salt_param(comps,salts,Z)
     return SaltParam(explicit_solvent,explicit_components,implicit_components,isalts,mat,lu(mat))
 end
 
-function SaltParam(model::ESElectrolyteModel)
+SaltParam(model::ESElectrolyteModel) = SaltParam(model,nothing)
+
+function SaltParam(model::ESElectrolyteModel,::Nothing)
     explicit_salt_param(component_list(model),auto_binary_salts(model),model.charge)
 end
 
+function SaltParam(model::ESElectrolyteModel,salts)
+    explicit_salt_param(component_list(model),salts,model.charge)
+end
+
 function component_list(m::SaltParam)
     if m.explicit_solvent
         return m.explicit_components

src/models/Electrolytes/electrolytes.jl

@@ -7,7 +7,7 @@ abstract type ISElectrolyteModel <: ElectrolyteModel end
 
 Obtains the stoichiometry matrix of `salts` made up of ions stored in the `model`.
 This will also check that the salt is electroneutral and that all ions are involved in the salts.
-If no `salts` argument is specified, it will be created via `Clapeyron.auto_binary_salts(model)`
+If no `salts` argument is specified, the salt pairings will be created via [`Clapeyron.auto_binary_salts`](@ref).
 
 """
 function salt_stoichiometry(model::ElectrolyteModel,salts = auto_binary_salts(model))
@@ -66,7 +66,7 @@ end
     molality_to_composition(model::ElectrolyteModel,m,zsolv = SA[1.0])
 
 Convert molality (mol/kg) to composition for a given model, salts, molality, and solvent composition.
-If no `salts` argument is specified, it will be created via `Clapeyron.auto_binary_salts(model)`
+If no `salts` argument is specified, the salt pairings will be created via [`Clapeyron.auto_binary_salts`](@ref).
 `zsolv` is the mole fraction of solvent components (in a salt-free basis)
 """
 function molality_to_composition(model::ElectrolyteModel,salts::Union{AbstractVector,GroupParam},m,zsolv=SA[1.],ν = salt_stoichiometry(model,salts))

src/models/Electrolytes/stability.jl

@@ -41,68 +41,3 @@ function tpd_plan(model::ISElectrolyteModel,z,is_liquidz,lle,id_test,K_test,pure
     end
     return plan
 end
-
-#=
-function tpd_plan(model::ESElectrolyteModel,z,is_liquidz,lle,id_test,K_test,pure_test)
-    plan = Tuple{Symbol,Symbol,NTuple{3,Int}}[]
-
-    if is_liquidz && id_test && !lle
-        push!(plan,(:ideal_gas,:vapour,0))
-    end
-
-    #=
-    if K_test
-        if is_liquidz
-            lle || push!(plan,(:K,:vapour,1))
-            push!(plan,(:K,:liquid,1))
-            push!(plan,(:K,:liquid,-1))
-            lle || push!(plan,(:K,:vapour,-1))
-        else
-            push!(plan,(:K,:liquid,1))
-            push!(plan,(:K,:liquid,-1))
-        end
-    end =#
-    Z = model.charge
-    _,i_elec_pivot = findmax(Z)
-    if pure_test
-        ids = sortperm(z)
-        ZZ = @view Z[ids]
-        if is_liquidz
-            for i in 1:length(z)
-                if iszero(ZZ[i])
-                    idx_solvent = ids[i]
-                    push!(plan,(:pure,:liquid,(idx_solvent,0,0)))
-                    for j in 1:length(z)
-                        if !iszero(ZZ[j])
-                            idx_elec = ids[j]
-                            xx = (idx_solvent,idx_elec,i_elec_pivot)
-                            i_elec_pivot != idx_elec && push!(plan,(:electrolyte_balanced,:liquid,xx))
-
-                        end
-                    end
-                end
-            end
-            if !lle
-                for i in 1:length(z)
-                    !iszero(ZZ[i]) && push!(plan,(:pure,:vapour,ids[i]))
-                end
-            end
-        else
-            for i in 1:length(z)
-                if iszero(ZZ[i])
-                    idx_solvent = ids[i]
-                    push!(plan,(:pure,:liquid,(idx_solvent,0,0)))
-                    for j in 1:length(z)
-                        if !iszero(ZZ[j])
-                            idx_elec = ids[j]
-                            xx = (idx_solvent,idx_elec,i_elec_pivot)
-                            i_elec_pivot != idx_elec && push!(plan,(:electrolyte_balanced,:liquid,xx))
-                        end
-                    end
-                end
-            end
-        end
-    end
-    return plan
-end
-=#