Models

abstract type Element{T <: AbstractFloat} end
abstract type SurfaceElement{T} <: Element{T} end
abstract type VolumeElement{T}  <: Element{T} end

Abstract base types for all elements.

struct Triangle{T} <: SurfaceElement{T}
    v1      ::Vector{T}   # position of the first node
    v2      ::Vector{T}   # position of the second node
    v3      ::Vector{T}   # position of the third node
    center  ::Vector{T}   # centroid of the triangle
    normal  ::Vector{T}   # normal vector of the triangle
    area    ::T           # area of the triangle
    distorig::T           # distance to the origin
end

Representation of a single surface triangle.

Special constructors

Triangle(
    v1  ::Vector{T},
    v2  ::Vector{T},
    v3  ::Vector{T}
)

Most commonly used constructor variant for creating a triangle by only specifying its nodes. The remaining member variables will automatically be computed via props.

struct Tetrahedron{T} <: VolumeElement{T}
    v1::Vector{T}       # position of the first node
    v2::Vector{T}       # position of the second node
    v3::Vector{T}       # position of the third node
    v4::Vector{T}       # position of the fourth node
    domain::Symbol      # element domain (solvent :Σ, solute :Ω, or :none)
end

Representation of a single tetrahedron.

Special constructors

Tetrahedron(
    v1::Vector{T},
    v2::Vector{T},
    v3::Vector{T},
    v4::Vector{T}
)

Sets domain to :none.

struct Charge{T <: AbstractFloat}
    pos::Vector{T}  # position of the charge
    val::T          # charge value
end

Representation of a single point charge.

Special constructors

Charge(
    posx::T,
    posy::T,
    posz::T,
    val ::T
)

Constructor variant with flat argument list for pos.

mutable struct Model{T, E <: Element{T}}
    nodes   ::Vector{Vector{T}  = Vector{T}[]    # mesh nodes
    elements::Vector{E}         = E[]            # mesh elements
    charges ::Vector{Charge{T}} = Charge{T}[]    # point charges in the molecule
    params  ::Option{T}         = defaultopt(T)  # system constants
end

System model representing a biomelecule in solvation, including a collection of point charges in the molecule and a set of system constants. The system can either be represented as a surface model (e.g., a collection of molecule surface triangles) or as a volume model (e.g., a collection of tetrahedra for the molecule and its surrounding space).

Model(ion::BornIon)

Converts the given Born ion into a triangle-based model, using Gmsh.jl for the mesh generation.

Supported keyword arguments

• lc_min::Real = 0.2 corresponds to Gmsh's "Mesh.CharacteristicLengthMin"
• lc_max::Real = 0.25 corresponds to Gmsh's "Mesh.CharacteristicLengthMax"

Return type

Model{T, Triangle{T}}

Model(xie::XieSphere)

Converts the given Xie sphere into a triangle-based model, using Gmsh.jl for the mesh generation.

Supported keyword arguments

• lc_min::Real = 0.12 corresponds to Gmsh's "Mesh.CharacteristicLengthMin"
• lc_max::Real = 0.13 corresponds to Gmsh's "Mesh.CharacteristicLengthMax"

Return type

Model{T, Triangle{T}}

function Model(
    mesh::GeometryBasics.Mesh{3, T, <: GeometryBasics.NgonFace{3}};
    charges::Vector{Charge{T}} = Charge{T}[],
    params::Option{T} = defaultopt(T)
)

Converts the given GeometryBasics.jl mesh into a triangle-based model.

Return type

Model{T, Triangle{T}}

mutable struct BornIon{T <: AbstractFloat}
    charge::Charge{T}                          # point charge at the sphere center
    radius::T                                  # sphere radius in Å
    params::Option{T} = defaultopt(BornIon{T}) # system constants
end

Single Born ion, that is, a monoatomic ion represented as a spherically symmetric domain with a single point charge located at its center ($ε_Ω = 1$).

Special constructors

BornIon(charge::T, radius::T, params::Option{T} = defaultopt(BornIon{T}))

Centers the sphere at $(0, 0, 0)^T$.

bornion(name::AbstractString, ::Type{Float64} = Float64)
bornion(name::AbstractString, ::Type{Float32})

Generator function for built-in Born ions:

Return type

BornIon{T}

mutable struct XieSphere{T}
    radius ::T                                 # radius of the origin-centered sphere
    charges::Vector{Charge{T}}                 # point charges in the sphere
    params ::Option{T}         = defaultopt(T) # system constants
end

System model of a dielectric sphere containing multiple point charges. On construction, the given point charge model will be translated and rescaled to fit inside an origin-centered sphere with the specified radius.

Special contructors

XieSphere(
    radius ::T,
    charges::Vector{Charge{T}},
    params ::Option{T}          = defaultopt(T);
    # kwargs
    compat ::Bool               = false
)

compat enables the compatibility mode and scales the model exactly like the reference implementation ([Xie16]). Use this flag if you intend to compare the results to the reference.

struct XieTestModel{T, M} end

Common abstraction for all Xie sphere-based test models.

struct LocalXieModel{T}
    radius ::T                 # radius of the origin-centered sphere
    charges::Vector{Charge{T}} # point charges in the sphere
    params ::Option{T}         # system constants
    len    ::Int               # number of terms to be computed
    M₁     ::Matrix{T}         # coefficients A₁ = C₁ for each charge
    M₂     ::Matrix{T}         # coefficients A₂ = C₂ for each charge
    M₃     ::Matrix{T}         # coefficients A₃ = C₃ for each charge
end

Representation of the local Poisson dielectric model described in [Xie16]. This model comprises a full XieSphere and the coefficients used for the computation of the electrostatic potentials.

Constructor

LocalXieModel(model::XieSphere{T}, len::Int)

The model is created solely from the given XieSphere and the number of terms to be used to approximate the original infinite sum (Eqs. 38a-b).

struct NonlocalXieModel1{T}
    radius ::T                 # radius of the origin-centered sphere
    charges::Vector{Charge{T}} # point charges in the sphere
    params ::Option{T}         # system constants
    len    ::Int               # number of terms to be computed
    M₁     ::Matrix{T}         # coefficients A₁ for each charge
    M₂     ::Matrix{T}         # coefficients A₂ for each charge
    M₃     ::Matrix{T}         # coefficients A₃ for each charge
end

Representation of the first nonlocal Poisson dielectric model described in [Xie16]. This model comprises a full XieSphere and the coefficients $A_{in}$ with $i = 1, 2, 3$ (cf. Eqs. (20a-c)) for each point charge in the model, which are used in the computation of the electrostatic potentials.

Constructor

NonlocalXieModel1(model::XieSphere{T}, len::Int)

The model is created solely from the given XieSphere and the number of terms to be used to approximate the original infinite sum (Eq. 18).

struct NonlocalXieModel2{T}
    radius ::T                 # radius of the origin-centered sphere
    charges::Vector{Charge{T}} # point charges in the sphere
    params ::Option{T}         # system constants
    len    ::Int               # number of terms to be computed
    M₁     ::Matrix{T}         # coefficients C₁ for each charge
    M₂     ::Matrix{T}         # coefficients C₂ for each charge
    M₃     ::Matrix{T}         # coefficients C₃ for each charge
end

Representation of the second nonlocal Poisson dielectric model described in [Xie16]. This model comprises a full XieSphere and the coefficients $C_{in}$ with $i = 1, 2, 3$ (cf. Eqs. (39a-c)) for each point charge in the model, which are used in the computation of the electrostatic potentials.

Constructor

NonlocalXieModel2(model::XieSphere{T}, len::Int)

The model is created solely from the given XieSphere and the number of terms to be used to approximate the original infinite sum (Eqs. 38a-b).