EChO

Electro-Chemical Optimizer

EChO is an toolkit for exploring structure and dynamics of electrochemical surfaces/interfaces under a fixed electrode potential and within a grand canonical ensemble of electrons.

Currently, EChO supports the following calculations at exact FIXED-POTENTIAL: local optimization, transition state search, molecular dynamics, and free energetics via thermodynamic integration.

It is an external standalone code, interacting with VASP via ASE interface, needless of any extra and elaborate patching on VASP!

Please make sure to cite the following papers if you use EChO in your research:

• J. Am. Chem. Soc. 2024, 146, 14, 9623–9630. [link] [bibtex]

• J. Am. Chem. Soc. 2025, accepted. [link] [bibtex]

Requirements

• Python 3.6 or higher
• ASE 3.22.1 or higher
• VASP 5.4.1 or higher, with VASPsol add-on

Installation

If your machine has Git installed, simply clone the repo to your local directory by:

git clone https://github.com/zishengz/echo

Or, you can also download and unzip the source code:

wget https://github.com/zishengz/echo/archive/refs/heads/main.zip
unzip main.zip
rm main.zip
mv main echo

After fetching the gocia repo, add it to your PYTHONPATH by:

export PYTHONPATH=$PYTHONPATH:`pwd`/echo/

Remember to add this export line to your ~/.bashrc or the submission script, so that EChO package is accessible by Python when you run the job.

You need to use the absolute path (you can check it by running pwd in Bash shell) for this purpose.

After these, run the following line to test:

python -c 'import echo'

If no error occurs, EChO should have been imported into your path!

ASE-related settings

In the jobs submission script, besides the PYTHONPATH, you should also set some environment variables for the ASE interface to VASP:

export PYTHONPATH=$PYTHONPATH:/xxx/echo-main
export VASPHOME=/xxx/vasp.x.x.x/bin
export VASP_COMMAND="mpirun -n $NSLOTS $VASPHOME/vasp_std"
export VASP_PP_PATH=/xxx/potentials/

The VASP_COMMAND would vary from machine to machine, depending on job scheduler and number of cores to use. You may need to adjust it yourself (and the script header, of course).

Tutorials

See the examples folder.