{"id":19706180,"url":"https://github.com/llnl/user-eph","last_synced_at":"2025-06-13T06:32:57.308Z","repository":{"id":66083057,"uuid":"132844616","full_name":"LLNL/USER-EPH","owner":"LLNL","description":" LAMMPS extension to capture electron-ion interaction. This is a mirror of https://gitlab.com/artuuuro/USER-EPH.","archived":false,"fork":false,"pushed_at":"2025-03-31T11:47:43.000Z","size":6431,"stargazers_count":13,"open_issues_count":3,"forks_count":7,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-29T16:48:13.393Z","etag":null,"topics":["cpp","electron-phonon-coupling","gpu","lammps","molecular-dynamics"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LLNL.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-05-10T03:38:20.000Z","updated_at":"2025-03-31T11:47:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"c89d892a-a596-4c98-b0b2-413148033fae","html_url":"https://github.com/LLNL/USER-EPH","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/LLNL/USER-EPH","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2FUSER-EPH","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2FUSER-EPH/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2FUSER-EPH/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2FUSER-EPH/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LLNL","download_url":"https://codeload.github.com/LLNL/USER-EPH/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2FUSER-EPH/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259594568,"owners_count":22881676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","electron-phonon-coupling","gpu","lammps","molecular-dynamics"],"created_at":"2024-11-11T21:34:29.875Z","updated_at":"2025-06-13T06:32:57.290Z","avatar_url":"https://github.com/LLNL.png","language":"C++","readme":"# USER-EPH\n\nLAMMPS extension (LAMMPS \"fix\") to capture electron-ion interaction and electronic stopping. LLNL-CODE-750832\n\nArtur Tamm (University of Tartu) \\\u003cartur.tamm@ut.ee\\\u003e\nAlfredo A. Correa (LLNL) \\\u003ccorreaa@llnl.gov\\\u003e\n\n## Updates/News\nI am planning to refactor the code a bit, so that it would be easier to expand the capabilities of the code in the future. The old codebase will be saved under the tag legacy-2023-11-22.\n\nYou can clone the legacy code with this command (you will see warnings about being in a detached state, but you can ignore them):\n```\ngit clone -b legacy-2023-11-22 https://gitlab.com/artuuuro/USER-EPH.git\n```\n\nSome planned changes:\n* Move to json format for inputs. This will enable to extend the input files without breaking older implementations. The json implementation will be based on nlohmann::json as it is low overhead and does not require any additional dependencies.\n* Remove old GPU implementation from the master branch\n* Rewrite the documentation\n* Create EPH parameterisations based on Leonid Zhigilei's data\n* Create EPH parameterisations based on Nikita Medvedev's data\n\n## Introduction\n\nIn LAMMPS, a \"fix\" is a plugin or extension to the main code that performs a specific operation on the atomistic system during\ntime-stepping or minimization. \nWe use this extension mechanism to generalize the two-temperature model to include electron-phonon coupling.\nThe fix implements a theory to model collision cascades, laser heating, and equilibration and to study energy transport, incorporating realistic electronic stopping power and electron-phonon coupling.\nThe theory is developed in the papers \"Langevin dynamics with spatial correlations as a model for electron-phonon coupling\" (https://dx.doi.org/10.1103/PhysRevLett.120.185501) and \"Electron-phonon interaction within classical molecular dynamics\" (https://link.aps.org/doi/10.1103/PhysRevB.94.024305).\n\n[[_TOC_]]\n\n## Installation Instructions\n\nFirst you need a version of LAMMPS (source code)\n```\n$ mkdir mywork\n$ cd mywork\n$ git clone https://github.com/lammps/lammps.git\n```\n\n### Compile the USER-EPH fix for CPUs\n \nGet USER-EPH (this plugin, you have to have access to the repository)\n```\n$ cd lammps/src\n$ git clone https://github.com/LLNL/USER-EPH.git\n```\n\nEdit LAMMPS' `Makefile` add the string ` user-eph ` to the `PACKUSER` variable (near line 68), for example:\n\n```Makefile\nPACKUSER = user-adios user-atc user-awpmd user-bocs user-cgdna user-cgsdk user-colvars \\\n    ... \n    user-sdpd user-sph user-tally user-uef user-vtk user-yaff \\\n    user-eph\n```\n\nEdit `MAKE/Makefile.mpi` and `MAKE/Makefile.serial` and add `-std=c++11` to the `CCFLAGs` varialbe to read `CCFLAGS = -g -O3 -std=c++11` (near line 10).\n\nExecute:\n```bash\n$ make yes-manybody yes-user-eph\n$ make -j 8 serial\n```\n\n(You can also enable other packages as needed)\n\nMake sure your MPI enviroment is setup already (`mpicxx` compiler wrapper works), this may require for example running `$ module load mpi/mpich-x86_64`\n\n```\n$ make -j 8 mpi\n```\n\nThe executables are `./lmp_mpi` (for parallel runs) `./lmp_serial` (for serial runs, testing), you can copy them elsewhere.\n\n### Compile for CUDA-enabled GPUs (optional)\n\nThe code is ported to GPUs, a CUDA toolkit is required to compile this version and a CUDA card(s) supporting architecture *at least* 6.0 (`sm_60`, like\n[Pascal, Volta, Turing, etc](https://en.wikipedia.org/wiki/CUDA#GPUs_supported). \nThe command `nvidia-smi` will give you details.\n\nIf not defined, set the CUDA environment variable (e.g. `/usr/local/cuda` or `/usr`)\n```bash\n$ echo $CUDA_HOME\n$ export CUDA_HOME=/usr/local/cuda \n```\n\nGo back to the LAMMPS GPU library directory (`cd ../../lammps/lib/gpu`) and modify the file `Makefile.linux.double` add and activate your CUDA architecture and if needed `CUDA_HOME` and `CUDA_INCLUDE`. For example (after line 10),\n\n```Makefile\n...\n#CUDA_HOME = /usr/local/cuda\nNVCC = nvcc -ccbin=cuda-c++   ### or, for example -ccbin=mpicxx\n\n# Kepler CUDA\n#CUDA_ARCH = -arch=sm_35\n# Tesla CUDA\n# CUDA_ARCH = -arch=sm_21\n# newer CUDA\n#CUDA_ARCH = -arch=sm_13\n# older CUDA\n#CUDA_ARCH = -arch=sm_10 -DCUDA_PRE_THREE\n# Pascal (your architecture)\nCUDA_ARCH = -arch=sm_60\n...\n```\n\nand compile the library and return to the USER-EPH\n\n```bash\n$ make -f Makefile.linux.double\n```\n\nGo to the USER-EPH directory\n```bash\n$ cd ../../../lammps/src/USER-EPH/lib\n```\n\nModify `Makefile` if needed (`CUDA_ARCH`, `CUDA_CODE`, `NVCCFLAGS`, `INCFLAGS`) and load necessary modules (e.g. `module load mpi/openmpi-x86_64`) buid\n\n```bash\n$ make\n```\n\nGo back to the source directory `lammps/src` and create a new file `MAKE/Makefile.mpi_gpu` \n\n```bash\n$ cd ../..\n$ cp MAKE/Makefile.mpi MAKE/Makefile.mpi_gpu\n```\n\nModify the `CCFLAGS` and `LIB` variables in the new `MAKE/Makefile.mpi_gpu` to read\n\n```Makefile\n...\nCCFLAGS =\t-g -O3 -std=c++11 -DFIX_EPH_GPU\n...\nLIB = -L../USER-EPH/lib -leph_gpu -lcuda -lcudart\n...\n```\n\n```bash\n$ make yes-user-eph\n$ make yes-gpu\n$ make -j mpi_gpu\n```\n\nThe GPU executable will be in `lmp_mpi_gpu`.\n\nThe use the GPU accelerated potentials you enable the GPU package when running LAMMPS\neither by supplying it on the command line or through run scripts.\n\n```bash\n$ cd USER-EPH/Examples/Example_5\n$ lmp_mpi_gpu -pk gpu 1 -sf gpu -i run.lmp\n```\n\nor\n\n```\n# LAMMPS input file run.lmp\npackage gpu 1\n...\npair eam/alloy/gpu \n...\nfix friction all eph/gpu\n...\n```\nThe `-pk gpu 1` and `-sf gpu` flags allow the use of a single lammps run script where\nthe last will try to substitute all fixes and pairs supporting gpu extension.\n\nSee also Example-5 for a possible input script using the GPU version. \n\n#### Note\n\nThe current GPU version of the fix is not multi-device aware, so in order to utilise all GPUs on a node, \nan equal number of tasks has to be used. Thus, `mpirun` has to be aware of gpus in order to assign correct GPUs \nto each task. As a workaround, GPUs can be set into a special mode to block multiple tasks running on one GPU card.\n\n## Usage\n\n* Take your MD input file\n* Add a line at the correct place, \n```\nfix [ID] [group-ID] eph [seed] [flags] [model] [rho_e] [C_e] [kappa_e] [T_e] [NX] [NY] [NZ] [T_infile] [freq] [Te_outfile] [beta_infile] [A] [B] [C...]\n```\nWhere:\n\n* `ID` -\u003e user-assigned name for the fix, [string, e.g. `ephttm` or `friction`]\n* `group-ID` -\u003e group of atoms to which this fix will be applied, [string, e.g. `all`]\n* `seed` -\u003e seed for random number generator [integer, e.g. 123]\n* `flags`: control of different terms or'd together [integer or bitmask]\n  * `1` -\u003e enable friction (only) (pure damping)\n  * `2` -\u003e enable random force (only) (not recommended)\n  * `3` -\u003e enable friction and random force (fixed e-temperature) \n  * `4` -\u003e heat equation (by FDM finite difference method) (decoupled from ions)\n  * `5` -\u003e enable friction and heat equation (no feedback from e-)\n  * `7` -\u003e enable friction, random force, and heat equation (coupled e-ions)\n* `model`: select model for friction and random force [integer]\n  * `1` -\u003e standard Langevin (for vanilla TTM with beta(rho))\n  * `2` -\u003e simple e-ph model (https://link.aps.org/doi/10.1103/PhysRevB.94.024305) (not recommended)\n  * `3` -\u003e e-ph with spatial correlations, with CM-correction only (https://arxiv.org/abs/1801.06610)\n  * `4` -\u003e e-ph with spatial correlations, full model (https://arxiv.org/abs/1801.06610)\n* `rho_e` -\u003e scaling parameter for the FDM grid [float, recommended `1.0`] [unitless]\n* `C_e` -\u003e electronic heat capacity per volume [float, e.g. `2.5e-6`] [in eV/K/Ang^3]\n* `kappa_e` -\u003e electronic thermal conductivity [float,  ignored for single grid point] [in eV/K/Ang/ps]\n* `T_e` -\u003e electronic temperature [float, e.g. `300`] [in K]\n* `NX`, `NY`, `NZ` -\u003e grid size in x, y, and z direction [integer, e.g. `1` `1` `1` sets single grid point]\n* `T_infile` -\u003e input filename for the FDM grid parameters and initial values [string or NULL]\n* `freq` -\u003e heat map output (`T_output`) frequency, `0` to disable [integer, e.g. `10`]\n* `Te_output` -\u003e output heat map filename (CUBE format) [string, e.g. `Te_output.cub`]\n* `beta_infile` -\u003e beta(rho) input filename [string, e.g. `NiFe.beta`]\n* `A`, `B`, `C...` -\u003e element type mapping [1 or more strings, `Ni Ni Fe`]\n~/Lassen/09_Techbase/TB_Bench/02_Bench/02_GPU/TB_12/02_2_nodes\nFor example the following line in LAMMPS input script, \nwill run the MD including the coupling to electrons, \nwithin the spatially correlated Langevin bath.\nThe electronic specific heat is assumed to be 2.5e-6 eV/K/Ang^3 (400000 J/m³/K) (see LinPRB772008) which is a good approximation for a range of electronic temperatures from 500 to 1500K. \nInitial electron temperature is set to 300K (and not from a file).\nWe use uniform tempetures (one grid element), therefore the heat conductivity is not relevant in this case.\n\n```\nfix ephttm all eph 123 7 4 1.0 2.5e-6 1.0 300.0 1 1 1 NULL 10 Te_output.cub Ni.beta Ni \n```\n\nThis fix produces two types of Lammps-internal results in addition to the normal MD:\n\n* vector with the energy and temperature of the electronic system\n  * `f_ID[1]` -\u003e Net energy transfer between electronic and ionic system\n  * `f_ID[2]` -\u003e Average electronic temperature\n \n* per atom values:\n  * `f_ID[i][1]` -\u003e site density\n  * `f_ID[i][2]` -\u003e coupling parameter\n\nTo access them in the output file add this to the LAMMPS input script:\n```\nfix out all print 1000 \"$(step) $(time) $(temp) $(f_ephttm[1]) $(f_ephtmm[2])\" file out.data screen no\ndump out all custom 10 strucs_out.dump.gz type x y z f_ephttm[1] f_ephttm[2]\n```\n\n### Beta(rho) input file\n\nThis file provides the electronic densities and beta(rho) functions for individual species (see https://dx.doi.org/10.1103/PhysRevLett.120.185501).\nThe format is described in `Doc/Beta/input.beta`. \nThe file is similar to EAM setfl format. \nThe beta(rho) function has units of [eV ps/Ang^2]. \nAn example is provided in `Examples/Beta/Ni_model_4.beta`.\n\n### heat equation FDM grid input file\n\nThis file is used to initialise FDM grid for the electronic system. \nThe format is described in `Doc/FDM/T_input.fdm`. \nThis allows fine control of the properties at various grid points. \nAlso, the grid can be larger than ionic system if energy reservoir far away is needed. \nGrid points can act as energy sources, sinks or walls (individual grid points updates can be deactivated).\nAn example of input file is provided in `Examples/FDM/T.in`.\nUnits are [Kelvin], [eV/Ang^3/ps], [unitless], [in eV/K/Ang^3] [eV/K/Ang/ps] for T, local source term, rho_e, Ce, kappa_e respectively.\n\n## Notes and limitations\n\n* The exact physical interpretation of beta(rho) changes with the precise model. \n* If `T_infile` is not `NULL` then `C_e`, `rho_e`, `kappa_e`, `T_e`, `NX`, `NY`, `NZ` are ignored and are read from the filename supplied. \nIf `NULL` is provided as the filename then the FDM grid is initialised with the parameters provided in the command.\n* The implementation of the model is applicable to alloys, but this has not been tested thoroughly yet.\n\n# Electron-ion coupling database\n\nUSER-EPH model requires for the user to supply electron-ion coupling parametrisations, analogous to empirical potentials, which will define the non-equilibrium dynamics of the system they are studying. As the creation of these files is rather involved (both computationally as well as work hours) we provide here an option to supply user supplied and peer reviewed parametrisations for open use by the general scientific community.\n\nSee [`Data/README.md`](Data/README.md) for currently published parametrisation along with references.\n\nIf you want to add your parametrisation with correct references, send a request with an e-mail to \\\u003cartur.tamm@ut.ee\\\u003e\n\n# Tutorial\n\nExamples can be found in `Examples/` directory. \nTo run them type `lmp_serial -i run.lmp` in the appropriate example directory and assuming executable is in `PATH`. \nSome of the examples may take long on older machines, so tweak the input file (`run.lmp`) accordingly. Every example contains a `README` file that describes what the runscript does.\n\n## Example 1\n\n`Examples/Example_1/`: \nIn this example a crystal structure is created and the model is applied with both the friction and random force terms. \nThe electrons are *kept* at constant temperature (300K). \nThis example illustrates the thermalisation process from 0K to the target temperature through electron-ion interaction only.\n\n```bash\n$ cd Examples/Example_1\n$ mypath/lmp_serial -i run.lmp\n```\n\nThe run will write to the file `out.data`, column 2 has the time (in ps), columns 3 and 5 have the ionic and the electronic temperature respectively.\n```\n$ gnuplot\n\u003e plot \"out.data\" u 2:3 w lp lw 2 t \"Tion\", \"out.data\" u 2:5 w lp lw 2 t \"Te\"\n```\nYou will see that the ionic temperature increases and approaches the (fixed) electronic temperature (300K).\n\n![Alt text](Examples/Example_1/Tout.png?raw=true \"Temperature Example 1\")\n\n## Example 2\n\n`Examples/Example_2/`: \nThis example illustrates the use cooling of the ionic systems due to electrons only. \nThis means that only the friction term acts on atoms and removes energy. \nThis is equivalent to having electrons at 0K.\n\n![Alt text](Examples/Example_2/Tout.png?raw=true \"Temperature Example 2\")\n\n## Example 3\n`Examples/Example_3/`: \nIn this example the full model with electronic heat equation FDM grid is used. \nThe crystal is created at equilibrium positions (0K) and it is heated by electrons. \nDuring the simulation the electronic system will cool and the ionic system heat. \nAt equilibrium both systems end up at the same temperature on average. \nAlso, this example illustrates the automatic initialisation of the FDM grid with constant parameters. \nThe electronic temperature at various grid points is written to files (one per step) (`T_out_XXXXXX`). \nFinal state of the grid is stored and can be reused in later simulations (`T.restart`).\n\nAlthough you can run in serial mode (like above), \nyou can try to run this example with in parallel, for example in 4 processes.\nMake sure your MPI environment works, for example you may need `$ module load mpi/mpich-x86_64`\n```\n$ mpirun -np 4 mypath/lmp_mpi -i run.lmp\n$ gnuplot\n\u003e plot \"out.data\" u 2:3 w lp lw 2 t \"Tion\", \"out.data\" u 2:5 w lp lw 2 t \"Te\"\n```\n\n![Alt text](Examples/Example_3/Tout.png?raw=true \"Temperature Example 2\")\n\n## Example 4\n`Examples/Example_4/`: \nThis example reads the FDM grid parameters from a file (`T.in`). \nIn this file a source term is added at line in the grid representing the energy dumped by swift ion. \nDuring the simulation the ionic system will heat while electron temperature will diffuse and due to gradient in the electronic system forces acting on atoms at different grid points will 'feel' different random forces in magnitude.\n\nAfter a few MD-TTM steps the electronic temperature field will look like this:\n\n![Alt text](Examples/Example_4/Tfieldout.png?raw=true \"Temperature Example 4\")\n\n## Example 5\n`Examples/Example_5/`:\n\nThis the same as Example 1, but with GPU-enabled acceleration.\n\n```bash\n$ cd Examples/Example_5\n$ mpirun -n 2 mypath/lmp_mpi_gpu -i run.lmp\n```\n\nOn a specialized cluster like LLNL/lassen you need a submission script\n\n```bash\n#!/bin/bash\n## job.bsub\n#BSUB -nnodes 2    # nodes\n#BSUB -W 120       # walltime in min\n#BSUB -G Bank      # your bank\n#BSUB -J Jobname   # name of job\n#BSUB -q pbatch    # queue to use (or pdebug)\n\n# Run info and srun job launch\njsrun -r4 -a1 -c1 -g1 -E OMP_NUM_THREADS=1 lmp_mpi_gpu -i run.lmp\n```\n```\n$ bsub \u003c job.bsub\n```\n\nTo run interactively:\n\n```bash\n$ bsub -Is jsrun -r4 -a1 -c1 -g1 ~/mywork/lammps/src/lmp_mpi_gpu -i run.lmp\n```\n(the arguments are: `-r`:num_resources (cpus), `-a`:mpi_tasks_per_resource, `-c`:cpus_per_resources, `-g`:gpus_per_resource)\n\n## Example 6\nThis example is same as example 4 except the parameters for electronic heat capacity and conduction are read from the input file and can depend on the temperature.\n\n# Benchmark, CPUs vs GPU\n\n\n![Combined code timing](Doc/Benchmark/Timing_Combined.png?raw=true \"Code benchmark Quartz and Lassen\")\n\n# Release\n\n## History\n\n- 2018/05/10 Initial Release\n- 2019/09/15 GPU port Release\n- 2019/10/29 Implemented C_e(T) and kappa_e(T) (breaking changes)\n\n## TODO\n\n- Implement CUBE format (http://paulbourke.net/dataformats/cube/) output for temperature field and (either all or some high energy) atoms in the same file. This format can be easily read with VisIt.\n\n## License and Copying\n\nUSER-EPH is licensed under the terms of the [GPL v3 License](/COPYING).\n\nUSER-EPH is not part of the LAMMPS code https://github.com/lammps/lammps\n\nIf you have any questions contact Artur Tamm \u003cartur.tamm@ut.ee\u003e or Alfredo Correa \u003ccorreaa@llnl.gov\u003e\n\n``LLNL-CODE-750832``\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllnl%2Fuser-eph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fllnl%2Fuser-eph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllnl%2Fuser-eph/lists"}