Skip to content

Database

Metals

mdinterface.database.metals.Metal111

Bases: Specie

FCC metal (111) surface slab as a Specie.

Generates a minimal orthogonal (1 x 2 x 3) unit cell using ASE :func:ase.build.fcc111, ready to be tiled by :meth:SimCell.add_slab.

Parameters:

Name Type Description Default
metal str

Element symbol (e.g. "Au", "Pt", "Cu"). Must be present in the built-in metal_params table.

 required
lj list of float

Custom [epsilon (kcal/mol), r0 (Å)] Lennard-Jones parameters. Defaults to the tabulated Heinz 2008 values.

 None
**kwargs

Forwarded to :class:~mdinterface.core.specie.Specie.

 {}

Examples:

::

from mdinterface.database import Metal111
gold = Metal111("Au")
Source code in mdinterface/database/metals.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
class Metal111(Specie):
    """
    FCC metal (111) surface slab as a Specie.

    Generates a minimal orthogonal (1 x 2 x 3) unit cell using ASE
    :func:`ase.build.fcc111`, ready to be tiled by :meth:`SimCell.add_slab`.

    Parameters
    ----------
    metal : str
        Element symbol (e.g. ``"Au"``, ``"Pt"``, ``"Cu"``).  Must be present
        in the built-in ``metal_params`` table.
    lj : list of float, optional
        Custom ``[epsilon (kcal/mol), r0 (Å)]`` Lennard-Jones parameters.
        Defaults to the tabulated Heinz 2008 values.
    **kwargs
        Forwarded to :class:`~mdinterface.core.specie.Specie`.

    Examples
    --------
    ::

        from mdinterface.database import Metal111
        gold = Metal111("Au")
    """

    def __init__(self, metal, lj=None, **kwargs):

        slab = fcc111(metal, size=(1,2,3), orthogonal=True, periodic=True)

        if lj is None:
            lj = metal_params[metal]
            lj_copy = {metal: [lj[0], round(lj[1] / np.power(2, 1/6), 5)]}
        else:
            lj_copy = lj

        super().__init__(atoms=slab, lj=lj_copy, **kwargs)

        return

    def __repr__(self):
        return f"{self.__class__.__name__}({self.resname})"

Water

mdinterface.database.molecules.Water

Bases: Specie

Water molecule with pre-parameterised force-field parameters.

Parameters:

Name Type Description Default
model str

Water model to use:

  • "ewald" -- SPC/E with Ewald-compatible charges (q_O=-0.83, q_H=0.415)
  • "charmm" -- CHARMM TIP3P (q_O=-0.834, q_H=0.417)
  • "spce" -- SPC/E (q_O=-0.8476, q_H=0.4238)
 ``"ewald"``
**kwargs

Forwarded to :class:~mdinterface.core.specie.Specie.

 {}

Examples:

::

from mdinterface.database import Water
water = Water(model="ewald")
Source code in mdinterface/database/molecules.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
class Water(Specie):
    """
    Water molecule with pre-parameterised force-field parameters.

    Parameters
    ----------
    model : str, default ``"ewald"``
        Water model to use:

        - ``"ewald"``  -- SPC/E with Ewald-compatible charges
          (q_O=-0.83, q_H=0.415)
        - ``"charmm"`` -- CHARMM TIP3P
          (q_O=-0.834, q_H=0.417)
        - ``"spce"``   -- SPC/E
          (q_O=-0.8476, q_H=0.4238)
    **kwargs
        Forwarded to :class:`~mdinterface.core.specie.Specie`.

    Examples
    --------
    ::

        from mdinterface.database import Water
        water = Water(model="ewald")
    """
    def __init__(self, model="ewald", **kwargs):

        if model.lower() == "ewald":
            b1 = Bond("O", "H", kr=450, r0=0.9572)
            a1 = Angle("H", "O", "H", kr=55, theta0=104.52)
            charges = [-0.83, 0.415, 0.415]
            lj = {"O": [0.102, 3.188], "H": [0.0, 1.0]}

        elif model.lower() == "charmm":
            b1 = Bond("O", "H", kr=450, r0=0.9572)
            a1 = Angle("H", "O", "H", kr=55, theta0=104.52)
            charges = [-0.834, 0.417, 0.417]
            lj = {"O": [0.1521, 3.1507], "H": [0.0460, 0.4]}

        elif model.lower() == "spce":
            b1 = Bond("O", "H", kr=1, r0=1.0)
            a1 = Angle("H", "O", "H", kr=1, theta0=109.47)
            charges = [-0.8476, 0.4238, 0.4238]
            lj = {"O": [0.1553, 3.1660], "H": [0.0, 0.0]}

        super().__init__("H2O", charges=charges, bonds=b1, angles=a1, lj=lj, **kwargs)
        return

Ions

mdinterface.database.ions.Ion

Bases: Specie

Monatomic ion Specie with tabulated force-field parameters.

Parameters:

Name Type Description Default
element str

Ion element symbol (e.g. "Na", "Cl", "K").

 required
ffield str

Force-field name. See :func:lookup_parameters for available options.

 ``"Jorgensen"``
chg_scaling float

Multiplicative scale factor applied to the formal charge. Use values less than 1 (e.g. 0.8) to mimic electronic polarisability in non-polarisable force fields.

 1.0
**kwargs

Forwarded to :class:~mdinterface.core.specie.Specie.

 {}

Examples:

::

from mdinterface.database import Ion
na = Ion("Na", ffield="Cheatham")
cl = Ion("Cl", ffield="Cheatham")
Source code in mdinterface/database/ions.py 
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
class Ion(Specie):
    """
    Monatomic ion Specie with tabulated force-field parameters.

    Parameters
    ----------
    element : str
        Ion element symbol (e.g. ``"Na"``, ``"Cl"``, ``"K"``).
    ffield : str, default ``"Jorgensen"``
        Force-field name.  See :func:`lookup_parameters` for available options.
    chg_scaling : float, default 1.0
        Multiplicative scale factor applied to the formal charge.  Use values
        less than 1 (e.g. 0.8) to mimic electronic polarisability in
        non-polarisable force fields.
    **kwargs
        Forwarded to :class:`~mdinterface.core.specie.Specie`.

    Examples
    --------
    ::

        from mdinterface.database import Ion
        na = Ion("Na", ffield="Cheatham")
        cl = Ion("Cl", ffield="Cheatham")
    """

    def __init__(self, element, ffield="Jorgensen", chg_scaling=1.0, **kwargs):

        charge, lj = lookup_parameters(element, ffield)
        lj = {element: lj}
        super().__init__(element, charges=chg_scaling*charge, lj=lj, **kwargs)

        return

mdinterface.database.ions.lookup_parameters(element, ffield)

Retrieve charge and LJ parameters for an ion from the database.

Parameters:

Name Type Description Default
element str

Ion element symbol (e.g. "Na", "Cl").

 required
ffield str

Force-field name (case-insensitive): "Jorgensen", "Cheatham", "Aqvist", "Sengupta", "Dang", "OPLS-AA". "merz" is accepted as an alias for "sengupta".

 required

Returns:

Name Type Description
charge float

Formal charge in elementary charge units.
lj list of float

[epsilon (kcal/mol), sigma (Å)] Lennard-Jones parameters.

Raises:

Type Description
ValueError

If element or ffield is not found in the database.
Source code in mdinterface/database/ions.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def lookup_parameters(element, ffield):
    """
    Retrieve charge and LJ parameters for an ion from the database.

    Parameters
    ----------
    element : str
        Ion element symbol (e.g. ``"Na"``, ``"Cl"``).
    ffield : str
        Force-field name (case-insensitive): ``"Jorgensen"``, ``"Cheatham"``,
        ``"Aqvist"``, ``"Sengupta"``, ``"Dang"``, ``"OPLS-AA"``.
        ``"merz"`` is accepted as an alias for ``"sengupta"``.

    Returns
    -------
    charge : float
        Formal charge in elementary charge units.
    lj : list of float
        ``[epsilon (kcal/mol), sigma (Å)]`` Lennard-Jones parameters.

    Raises
    ------
    ValueError
        If *element* or *ffield* is not found in the database.
    """
    try:
        if ffield.lower() == "merz":
            ffield = "sengupta"
        charge = ions_parameters[element]["charge"]
        lj = ions_parameters[element]["ffield"][ffield.lower()]
        return charge, lj
    except KeyError as e:
        raise ValueError(f"Invalid element or force field: {e}")

Noble gases

mdinterface.database.nobles.NobleGas

Bases: Specie

Class representing a noble gas atom with LJ parameters.

Args: element (str): The chemical symbol of the noble gas (He, Ne, Ar, Kr, Xe, Rn). ffield (str): The force field to use for parameters (default is "opls"). **kwargs: Additional keyword arguments to pass to the Specie superclass.

Source code in mdinterface/database/nobles.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class NobleGas(Specie):
    """
    Class representing a noble gas atom with LJ parameters.

    Args:
        element (str): The chemical symbol of the noble gas (He, Ne, Ar, Kr, Xe, Rn).
        ffield (str): The force field to use for parameters (default is "opls").
        **kwargs: Additional keyword arguments to pass to the Specie superclass.
    """

    def __init__(self, element, ffield="vrabec", **kwargs):

        charge, lj_params = lookup_noble_gas_parameters(element, ffield)

        # Create single atom
        atom = ase.Atoms(element, positions=[(0.0, 0.0, 0.0)])

        # Set up LJ parameters
        lj = {element: lj_params}

        super().__init__(atoms=atom, charges=charge, lj=lj, **kwargs)

        return

Graphene

mdinterface.database.graphene.Graphene

Bases: Specie

Single graphene sheet with OPLS-AA force-field parameters.

The unit cell is built with :func:ase.build.graphene and the interlayer spacing is set to 3.35 Å. Bond, angle, dihedral, and improper parameters follow the OPLS-AA graphene parametrisation.

Parameters:

Name Type Description Default
**kwargs

Forwarded to :class:~mdinterface.core.specie.Specie.

 {}

Examples:

::

from mdinterface.database import Graphene
grap = Graphene()
Source code in mdinterface/database/graphene.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
class Graphene(Specie):
    """
    Single graphene sheet with OPLS-AA force-field parameters.

    The unit cell is built with :func:`ase.build.graphene` and the
    interlayer spacing is set to 3.35 Å.  Bond, angle, dihedral, and
    improper parameters follow the OPLS-AA graphene parametrisation.

    Parameters
    ----------
    **kwargs
        Forwarded to :class:`~mdinterface.core.specie.Specie`.

    Examples
    --------
    ::

        from mdinterface.database import Graphene
        grap = Graphene()
    """
    def __init__(self, **kwargs):
        system = ase.build.graphene()
        system.cell[-1][-1] = 3.35
        g_b = Bond("C", "C", kr=469, r0=1.4)
        g_d = Dihedral("C", "C", "C", "C", A1=7.25, A2=0, A3=-7.25, A4=0, A5=0)
        g_i = Improper(a1="C", K=1.1, d=-1, n=2)
        g_a = Angle("C", "C", "C", kr=63, theta0=120)
        lj = {"C": [0.07, 3.54996412]}

        super().__init__(system, bonds=g_b, dihedrals=g_d, impropers=g_i, angles=g_a, lj=lj, **kwargs)

        return