Compressed4DMatrix{T}

A compressed storage that represents interactions between association sites of different components.

Conceptual Model

Consider a system with nc components. Each component i has n_i association sites, numbered 1..n_i. The full association matrix is of size N × N, where N = sum(n_i), and its entries are indexed by (component, site) pairs:

(i, a) ↔ (j, b)

The matrix is symmetric under exchange of the two pairs:

A[(i,a), (j,b)] == A[(j,b), (i,a)]

To avoid storing duplicate entries, only one triangular half is kept:

• For i < j: store all (a,b) pairs (no symmetry within the block).
• For i == j: store only a ≤ b (self‑association symmetric).

The storage exploits the block structure: each component i has a contiguous range of site indices determined by site_offsets. The data is stored as a flat vector values and a parallel vector indices of encoded integers that uniquely identify each stored (i,j,a,b) tuple.

External Interface

• m[i,j] returns an AssocView that behaves like a dense matrix of size n_i × n_j (or n_j × n_i if the block is stored transposed).

Indexing this view returns the appropriate value, handling symmetry and transposition automatically.

• dropzeros!(m) removes entries whose value is zero (the structural shape remains).

This type is used internally in Clapeyron.jl as the storage type for AssocParam.

Constructors

Several constructors are provided to create a Compressed4DMatrix from different input forms:

1. From block sizes – the most basic constructor:

   Compressed4DMatrix{T}(bsizes::AbstractVector{Int})

   where bsizes[i] is the number of association sites for component i. Creates an empty matrix (all values zero) with the specified block structure.

2. From a matrix of matrices – useful when a full block matrix is already assembled:

   Compressed4DMatrix(x::AbstractMatrix{<:AbstractMatrix{T}})

   x must be square (nc × nc), where nc is the number of components. Each x[i,j] is a matrix of size n_i × n_j (or n_j × n_i if only one triangular half is provided; the constructor will handle transposition). The diagonal blocks x[i,i] must be square and symmetric (only the upper triangle is used).

3. From explicit list of 4‑tuples – to set specific entries:

   Compressed4DMatrix(vals::AbstractVector, ijab::AbstractVector{NTuple{4,<:Integer}})

   where each tuple (i, j, a, b) specifies a component‑site pair, and vals gives the corresponding value. The entries can be in any order; they will be canonicalised and sorted internally. Duplicate indices will overwrite the earlier value.

4. From separate ij and ab vectors – for convenience:

   Compressed4DMatrix(vals::AbstractVector, ij::Vector{NTuple{2,Int}}, ab::Vector{NTuple{2,Int}})

   similar to the constructor from (i, j, a, b) indices, but the component and site indices are in different vectors.

5. Empty constructor:

   Compressed4DMatrix{T}()

   creates an empty matrix with no components (useful as a placeholder).

assoc_pair_length(model::EoSModel)

Indicates the number of pair combinations between the different sites in an association model. By default uses length(assoc_shape(model).values).

Example:

julia> model = PCSAFT(["water"])
PCSAFT{BasicIdeal} with 1 component:
 "water"
Contains parameters: Mw, segment, sigma, epsilon, epsilon_assoc, bondvol

julia> model.params.bondvol
AssocParam{Float64}["water"]) with 1 value:
("water", "e") >=< ("water", "H"): 0.034868

julia> Clapeyron.assoc_pair_length(model)
1

assoc_similar(mat::Compressed4DMatrix)
assoc_similar(mat::Compressed4DMatrix,::Type{𝕋}) where 𝕋 <:Number

Returns a Clapeyron.Compressed4DMatrix of the same shape as the input, with the same element type as 𝕋.

assoc_similar(param::SiteParam)
assoc_similar(param::SiteParam,::Type{𝕋}) where 𝕋 <:Number)

Returns a Clapeyron.Compressed4DMatrix with the same number of components as the input AssocParam, with the same element type as 𝕋. All site combinations are filled.

assoc_options(model::EoSModel)

Returns association options used in the association solver.

assoc_strength(model::EoSModel,V,T,z,i,j,a,b,data = Clapeyron.data(Model,V,T,z))
Δ(model::EoSModel,V,T,z,i,j,a,b,data = Clapeyron.data(Model,V,T,z))

Calculates the asssociation strength between component i at site a and component j at site b.

Any precomputed values can be passed along by calling Clapeyron.data.

Example

julia> model = PCSAFT(["water"])
PCSAFT{BasicIdeal} with 1 component:
 "water"
Contains parameters: Mw, segment, sigma, epsilon, epsilon_assoc, bondvol

julia> model.params.bondvol.values
Clapeyron.Compressed4DMatrix{Float64, Vector{Float64}} with 1 entry:
 (1, 1) >=< (1, 2): 0.034868

julia> Clapeyron.assoc_strength(model,2.5e-5,298.15,[1.0],1,1,1,2) #you can also use Clapeyron.Δ
1.293144062056963e-26

#PCSAFT precomputed data: (d,ζ₀,ζ₁,ζ₂,ζ₃,m̄)
julia> _data = Clapeyron.data(model,2.5e-5,298.15,[1.0])
([2.991688553098391e-10], 1.3440137996322956e28, 4.020870699566213e18, 1.2029192845380957e9, 0.3598759853853927, 1.0656)

julia> Clapeyron.Δ(model,2.5e-5,298.15,[1.0],1,1,1,2,_data)
1.293144062056963e-26

assoc_fractions(model::EoSModel, V, T, z,data = nothing)

Returns the solution for the association site fractions. Used internally by all models that require association. The result is of type PackedVectorsOfVectors.PackedVectorOfVectors, with length = length(model), and x[i][a] representing the empty fraction of the site a at component i.

Example:

julia> model = PCSAFT(["water","methanol","ethane"],assoc_options = AssocOptions(combining = :esd))
PCSAFT{BasicIdeal} with 3 components:
 "water"
 "methanol"
 "ethane"
Contains parameters: Mw, segment, sigma, epsilon, epsilon_assoc, bondvol

julia> x = Clapeyron.assoc_fractions(model,2.6e-5,300.15,[0.3,0.3,0.4]) #you can also use `Clapeyron.X`
3-element pack(::Vector{Vector{Float64}}):
 [0.041396427041509046, 0.041396427041509046]
 [0.018874664357682362, 0.018874664357682362]
 0-element view(::Vector{Float64}, 5:4) with eltype Float64