Home

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

This will require the OpenBLAS library and the Rust compiler.

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

Then install using the provided makefile: make install

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 and here.

A full guide for parameterizing an input yourself using AmberTools can be found here.

Using pyRISM

As a Command Line Interface (CLI)

pyRISM can be used as a CLI tool with the command rism:

rism [OPTIONS] <inputfile.toml>

The list of options:

[-h|--help]      Show help message
[-c|--compress]  Compress the solvent-solvent problem for future use
[-q|--quiet]     Suppress all output from solver (DEFAULT)
[-v|--verbose]   Print basic information from solver
[-l|--loud]      Print all information from solver

The default behaviour of pyRISM is to write all outputs to a .csv file. This is not a stable feature and is bound to change. Varying levels of information can be emitted from the solver with the appropriate verbosity flag.

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
.td	Thermodynamical Data
.diag	Solver and Timing diagnostics file

Fundamentally, these files are all .csv files (apart from the last two), with different extensions to indicate what data they represent.

As a Library

Currently, the Rust and Python APIs for pyRISM are incredibly minimal. DOCUMENTATION COMING SOON.