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

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
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

Take, for example, the input file for an argon dimer as a solute in a solution of liquid argon.

[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.diargon]
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]
]

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.data_vv.c # the direct correlation function for the solvent-solvent problem
mol.data_uv.t # the indirect correlation function for the solute-solvent problem (if available)

The following fields are available to the data_vv and data_uv classes:

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