Skip to content

Home

Jump to bottom
2AUK edited this page Mar 25, 2023 · 15 revisions

Welcome to the pyRISM wiki!

The wiki will show you how to install, use and set up a minimal workflow for RISM calculations with pyRISM.

Installing pyRISM

pyRISM can be installed locally using pip, Python's default package installer.

Clone the repository: git clone https://github.com/2AUK/pyRISM.git

Then cd into the cloned directory and build the code: pip install -r requirements.txt .

Or if you want to install it in development mode: pip install -r requirements.txt -e .

The -e flag means that it will be installed as an editable install---you won't need to reinstall pyRISM if you make any changes to the code.

Structure of an Input File

pyRISM uses the TOML file format to describe inputs for a given RISM problem. The TOML file has 4 sections:

  • [system]
  • [params]
  • [solvent]
  • [solute]

[solute] is an optional section and if given, then the specified solute molecule is inserted into the problem with the assumption of infinite dilution.

The [system] section describes the thermodynamic state of the problem, the units, and the sampling grid. The fields are as follows:

Field Meaning
temp System Temperature
kT Boltzmann Constant for defining input units
kU Boltzmann Constant for defining output (Solvation Free Energy) units
charge_coeff Constant to scale Coulomb interaction
npts Number of Grid Points
Radius Radius over which calculation is done
lam Number of Cycles for Charging

The [params] section controls the choice of potential, integral equation and closure and solver along with the parameters that tune the selected solver.

Field Meaning
potential Potential Function: 'LJ', 'HS'
closure Closures: 'HNC', 'KH', 'PY', 'PSE-1', 'PSE-2', 'PSE-3'
IE Integral Equations: 'XRISM', 'DRISM'
solver Solver: 'Picard', 'Ng', 'MDIIS'
depth MDIIS Depth (if selected)
picard_damping Mixing/damping parameter for Picard steps
mdiis_damping Mixing/damping parameter for MDIIS steps (if selected)
itermax Maximum Number of Iterations
tol Tolerance Criterion for Convergence

The [solvent] and [solute] sections specify the coordinates and force-field parameters of the solvent and solute species.

Field Meaning
nsv/nsu Total Number of Solvent/Solute Sites across all species (respectively)
nspv/nspu Number of Solvent/Solute Species
ns Number of Sites for a Species
dens Number Density in 1/A^3 for a Species

Each species is defined as a subsection in the [solvent]/[solute], for example, water with 0.1M NaCl:

[solvent]
nsv = 5
nspv = 3
[solvent.water]
dens = 3.3272748E-02
ns = 3
"O" = [
    [78.15, 3.1658, -0.8476], 
    [0.0, 0.0, 0.0]
]

"H1" = [
    [7.815, 1.1658, 0.4238],
    [1.0, 0.0, 0.0]
] 

"H2" = [
    [7.815, 1.1658, 0.4238],
    [-3.33314000e-01, 9.42816000e-01, 0.00000000e+00]
]

[solvent.na]
dens = 0.06022E-3
ns = 1
"Na" = [
    [50.322, 2.584, 1.0],
    [0.0, 0.0, 0.0]
]

[solvent.cl]
dens = 0.06022E-3
ns = 1
"Cl" = [
    [50.322, 4.401, -1.0],
    [0.0, 0.0, 0.0]
]

A full example of a toml is given below for an argon dimer in a solution of argon liquid.

[system]
temp = 200
kT = 1.0
kU = 0.00198720414667
charge_coeff = 167101.0
npts = 512
radius = 10.24
lam = 1

[params]
potential = "LJ"
closure = "HNC"
IE = "XRISM"
solver = "MDIIS"
depth = 5
picard_damping = 0.001
itermax = 10000
tol = 1E-12

[solvent]
nsv = 1
nspv = 1

[solvent.argon]
dens = 0.02
ns = 1
"Ar" = [
    [115.8875283, 3.4, 0.0],
    [0.00000000e+00, 0.00000000e+00, 0.00000000e+00]
]


[solute]
nsu = 2
nspu = 1

[solute.argon_dimer]
dens = 0.0
ns = 2
"Ar1" = [
      [115.8875283, 3.4, 0.0],
      [0.0, 0.0, 0.0]
]

"Ar2" = [
      [115.8875283, 3.4, 0.0],
      [2.0, 0.0, 0.0]
]

More examples can be seen here.

Using pyRISM

As a Command Line Interface (CLI)

pyRISM can be used as a CLI tool with the command pyrism: pyRISM [INPUT.toml] -w [all|duv]

pyRISM will silently run a calculation. Passing all to the -w flag will output all results from pyRISM (the solvent-solvent and solute-solute correlation functions and the solvation free energy density). -w duv only outputs the solvation free energy density.

If you want pyRISM to output some system and iteration information, the verbosity flag can be be passed as such: pyRISM [INPUT.toml] -v -w [all|duv]

The outputs of pyRISM are given in the table:

File Extension Meaning
.cvv Solvent-Solvent Direct Correlation Function
.tvv Solvent-Solvent Indirect Correlation Function
.hvv Solvent-Solvent Total Correlation Function
.gvv Solvent-Solvent Radial Distribution Function
.cuv Solute-Solvent Direct Correlation Function
.tuv Solute-Solvent Indirect Correlation Function
.huv Solute-Solvent Total Correlation Function
.guv Solute-Solvent Radial Distribution Function
.duv Solvation Free Energy Density

Fundamentally, these files are all .csv files, with different extensions to indicate what data they represent.

As a Library

Currently, the API for pyRISM is very minimal (this will change in the future). A simple calculation can be run from a python script as such:

from pyrism import RismController

mol = RismController("input.toml")
mol.initialise_controller()
mol.do_rism() # or mol.do_rism(verbose=True) if you want system and iteration information
mol.write_output() # or mol.write_output(duv_only=True) if you only want to output the solvation free energy density

Once the RISM problem as been solved, the converged solutions can be accessed with the data_vv and data_uv (if a solute-solvent problem was defined) fields:

mol.vv.c # the direct correlation function for the solvent-solvent problem
mol.uv.t # the indirect correlation function for the solute-solvent problem (if available)

The following fields are available to the vv and uv classes, where the size for each array is given in terms of (npts, ns1, ns2) - the number of points, the first number of sites and the second number of sites. ns1 corresponds to the number of solvent sites for vv and to the number of solute sites for uv. ns2 corresponds to the number of solvent sites in both cases.

Field Meaning
vv.c Direct Correlation Function (npts, ns1, ns2)
vv.t Indirect Correlation Function (npts, ns1, ns2)
vv.h Total Correlation Function (npts, ns1, ns2)
vv.g Radial Distribution Function (npts, ns1, ns2)
vv.w Intramolecular Correlation Function (npts, ns1, ns2)
vv.p Densities Matrix (not available for data_uv due to infinite dilution approximation) (ns1, ns2)
vv.u Total Potential Energy (npts, ns1, ns2)
vv.u_sr Short-range Potential Energy (npts, ns1, ns2)
vv.ur_lr Long-range Potential Energy in Real Space (npts, ns1, ns2)
vv.uk_lr Long-range Potential Energy in Fourier Space (npts, ns1, ns2)
vv.B Thermodynamic Beta (scalar)
vv.grid.npts Number of Point on Grid (scalar)
vv.grid.radius Radius over which RISM problem is solved (in Angstroms) (scalar)
vv.grid.ri Real Space Grid (npts)
vv.grid.ki Fourier Space Grid (npts)
vv.grid.d_r Real Space Grid Spacing (scalar)
vv.grid.d_k Fourier Space Grid Spacing (scalar)

Similarly, the Solvation Free Energies (SFEs) and Solvation Free Energy Densities (SFEDs) are stored in dicts:

mol.SFE['KH'] # SFE for Kovalenko-Hirata
mol.SFED['GF'] # SFED for Gaussian-Fluctuations

The currently available keys for the dicts are 'KH', 'HNC', 'GF'.

Clone this wiki locally