v5.11.0

Human generated release notes

• Polariton model for Shin-Metiu Hamiltonian (Yuchen Wang of Norah Hoffmann's group)
• kc-RPMD for classical nuclear limit is fully-functional (Victor Suarez of Joshua Kretchmer's group)
• added Langevin thermostat (Victor Suarez of Joshua Kretchmer's group)
• citools module for handling configuration state functions CSFs of different spin multiplicities, as well as related functions such as recursive calculation of Clebsch-Gordan coefficients, determinants reordering, and preparation of determinant-to-CSF transformation matrices, interface for MOPAC (Alexey Akimov)
• simplified version for generating CSF coefficients of the singlet states (Kevin Walsh)
• large collection of TSH recipes (Mohammad Shakiba of Alexey Akimov's group)
• fix of the DISH approach for Schwartz 1 decoherence time scheme (Mohammad Shakiba of Alexey Akimov's group)
• Read-the-docs initiation, revised overall README.md and added related information pages (Alexey Akimov)
• latest updates of the Bohmian module, PyTorch Hamiltonians for exact DVR calculations

Autogenerated release notes

What's Changed

• add files for Shin–Metiu-Polariton model by @YuchenWang2015 in #257
• Revision of step 3 mapping function and printing of average decoherence rate by @MohammadShakiba in #258
• Devel by @suarez-va in #259
• upload Shin_metiu_dvr model by @YuchenWang2015 in #260
• add a section for saving .h5 file by @YuchenWang2015 in #261
• Recipes for TSH + DISH with Schwartz 1 by @MohammadShakiba in #262
• Added single excitation specific functions to citools by @ktwalsh in #263

New Contributors

• @YuchenWang2015 made their first contribution in #257
• @ktwalsh made their first contribution in #263

Full Changelog: v5.10.1...v5.11.0

Libra v5.10.1: Bohmian dynamics, PyTorch DVR, FISH, revised atomistic workflows

Human-added content

Major additions:

• Bohmian dynamics module in PyTorch - uses multivariate Cauchy-Lorentz trajectory basis functions to represent the probability density, automatic differentiation to compute derivatives needed to construct quantum potential and differentiate it to obtain quantum forces, uses partial vectorization for efficiency; this release comes with the revision of the manuscript "Stable Direct Dynamics with Quantum Potential: Lorentzian Trajectory Basis Function is All You Need" that describes the methodology and shows the method's performance;
• Highly-efficient DVR solvers via PyTorch - implement exact numerical solution of TD-SE for adiabatic and non-adiabatic dynamics. Way faster than the previous C++ implementation. Very convenient to use as well.
• NA-MD recipes - a collection of standardized recipes defining various quantum-classical methodologies now comes with Libra. This should minimize the inconsistencies of defining such recipes by different users.
• FISH (fully-integrated surface hopping) - this method was already available in the previous version, but now it is finalized with few minor fixes. The relevant publication is now available: Han, D.; Shakiba, M.; Akimov, A. V. "Fully-Integrated Surface Hopping as Quantum Decoherence Correction in Nonadiabatic Dynamics" J. Phys. Chem. Lett. 2025, 16, 28, 7168–7176
• LDR (local diabatic representation) approach for exact quantum dynamics on a grid - a new module written in PyTorch is added and is nearly finalized, the corresponding article in preparation.
• Interface to ODIN code for correct calculations of time-overlaps with DFTB+ - this is now added, the corresponding DFTB+/Libra interface and workflows are revised. In general, this helps obtain significantly more reasonable results than before, but care should be exercised when using SK files - only correctly-generated ones can be used.
• Revised atomistic workflows - in particular, the calculations of the overlaps and time-overlaps of Slater determinants is now corrected, the mapping functions are revised, the phase factors previously given in the code are dropped. This does affect the calculations of TD-DFT overlaps and time-overlaps, and helps minimize the presence of "sudden jumps" in population dynamics. At the same time, our tests show that previous workflow still yielded close numerical results in many cases

Minor changes and additions:

• improved documentation, especially regarding the installation procedures,
• fixed bugs in Ferretti's model
• added several model Hamiltonians written with PyTorch
• fixed CITATION.cff for Zenodo compatibility

Auto-generated content

What's Changed

• Debug the Ferretti's model by @DaehoHan in #254
• Added the LDR solver with PyTorch by @DaehoHan in #255
• Fix coefficient initialization in LDR by @DaehoHan in #256

Full Changelog: v5.9.0...v5.10.0
Full Changelog: v5.10.0...v5.10.1

Libra v5.10.0: Bohmian dynamics, PyTorch DVR, FISH, revised atomistic workflows

Human-added content

Major additions:

• Bohmian dynamics module in PyTorch - uses multivariate Cauchy-Lorentz trajectory basis functions to represent the probability density, automatic differentiation to compute derivatives needed to construct quantum potential and differentiate it to obtain quantum forces, uses partial vectorization for efficiency; this release comes with the revision of the manuscript "Stable Direct Dynamics with Quantum Potential: Lorentzian Trajectory Basis Function is All You Need" that describes the methodology and shows the method's performance;
• Highly-efficient DVR solvers via PyTorch - implement exact numerical solution of TD-SE for adiabatic and non-adiabatic dynamics. Way faster than the previous C++ implementation. Very convenient to use as well.
• NA-MD recipes - a collection of standardized recipes defining various quantum-classical methodologies now comes with Libra. This should minimize the inconsistencies of defining such recipes by different users.
• FISH (fully-integrated surface hopping) - this method was already available in the previous version, but now it is finalized with few minor fixes. The relevant publication is now available: Han, D.; Shakiba, M.; Akimov, A. V. "Fully-Integrated Surface Hopping as Quantum Decoherence Correction in Nonadiabatic Dynamics" J. Phys. Chem. Lett. 2025, 16, 28, 7168–7176
• LDR (local diabatic representation) approach for exact quantum dynamics on a grid - a new module written in PyTorch is added and is nearly finalized, the corresponding article in preparation.
• Interface to ODIN code for correct calculations of time-overlaps with DFTB+ - this is now added, the corresponding DFTB+/Libra interface and workflows are revised. In general, this helps obtain significantly more reasonable results than before, but care should be exercised when using SK files - only correctly-generated ones can be used.
• Revised atomistic workflows - in particular, the calculations of the overlaps and time-overlaps of Slater determinants is now corrected, the mapping functions are revised, the phase factors previously given in the code are dropped. This does affect the calculations of TD-DFT overlaps and time-overlaps, and helps minimize the presence of "sudden jumps" in population dynamics. At the same time, our tests show that previous workflow still yielded close numerical results in many cases

Minor changes and additions:

• improved documentation, especially regarding the installation procedures,
• fixed bugs in Ferretti's model
• added several model Hamiltonians written with PyTorch

Auto-generated content

What's Changed

• Debug the Ferretti's model by @DaehoHan in #254
• Added the LDR solver with PyTorch by @DaehoHan in #255
• Fix coefficient initialization in LDR by @DaehoHan in #256

Full Changelog: v5.9.0...v5.10.0

v5.9.0

What's Changed

Human-generated description

• this version contains the finalized version of QTSH - see the paper here: Han, D.; Martens, C. C.; Akimov, A. V. "Generalization of Quantum-Trajectory Surface Hopping to Multiple Quantum States" J. Chem. Theory Comput. 2025 20, 5022-5042 https://doi.org/10.1021/acs.jctc.4c01751
• the restricted path integral (RPI) code and workflow is up - the manuscript is about to be submitted
• autopep8 tool applied to all of the Pyhon files to cleanup the style
• ongoing KC-RPMD developments
• the TRPES ("time-resolved photoelectron spectrogram") plotting script is added
• active state calculations from the LD - a small but potentially far-going fix
• added plotting of UV-vis/PDOS/energy vs time and population dynamics
• added Gu-Franco decoherence scheme
• added correct GFSH (the prior one conceptually aligns with the GFSH, but may be technically different, which is indeed seen in some tests!)
• some SQC and MMST variables and functions are added, but they are still in their infancy

Automatically-generated info

• Debug the phenol model by @DaehoHan in #235
• Add coherence indicator calculating and plotting routines by @DaehoHan in #236
• Update base_matrix for AppleClang by @foxtran in #234
• Updated Code: added kcrpmd auxiliary variable variables as double vector by @suarez-va in #240
• Update CMakeLists by @foxtran in #237
• add fucntion for UV-Vis spectrum by @SpringDabao in #238
• added kcrpmd_vars_status and allocate_kcrpmd() to libdyn.cpp, added placeholders for kcrpmd effective potential by @suarez-va in #241
• Add the force options in QTSH by @DaehoHan in #243
• Added new generate_m_matrices() function, temporarily just copying children hamiltonian by @suarez-va in #245
• added remaining KC-RPMD potential functions, effective potential now working by @suarez-va in #247
• step4 plot by @KosarYasin in #249
• Add the missing scipy.sparse dependency to trpes.py by @DaehoHan in #250
• Restructured code to minimize number of function calls, added in KCRPMD forces. Created new RPMD file for general RPMD calls by @suarez-va in #252
• Add the RPI workflow by @DaehoHan in #253

New Contributors

• @suarez-va made their first contribution in #240
• @KosarYasin made their first contribution in #249

Full Changelog: v5.8.1...v5.9.0

Libra v5.8.1

What's Changed

Human-generated description:

• Cleaned up and optimized the F-tracking and tNAC phase correction methodologies, added some experimental functions related to it;
• libint2 wrapper of higher moments in GTO basis (x, y, z, x^2, xy, ... z^3);
• important bug fixes in the molint implementation of some integrals with Gaussian functions, added the corresponding documentation/derivations;
• ChatGPT-generated implementation of the Munkres-Kuhn algorithm;
• Added new model Hamiltonian for phenol molecule;
• on-going development of the QTSH methodology
• added a good amount of testing modules for pytest (at the Python level)
• multiple minor and not-so-minor fixes and language style impovements, adding clang support by @foxtran

Automatically-generated info:

• Add diabatic hop features to FSSH-2 and FSSH-3 by @DaehoHan in #218
• Skipping the active state computation in the other rep if not necessary by @DaehoHan in #219
• Spin adapted configuration + bug fix for saving sd files by @MohammadShakiba in #221
• bug fix for CP2K pdos labels returning empty list by @MohammadShakiba in #222
• Fix the loop in printing 2D wavepackets by @DaehoHan in #226
• Minor fixes by @foxtran in #224
• Fix some compilation warnings/error by @foxtran in #227
• Fix qtag_potential: two overloads with and without AA-BB-CC by @foxtran in #228
• add function for fitting population by @SpringDabao in #231
• Add deco time test by @DaehoHan in #230
• New Libint functions for computing the integrals in GTOs with Cartesian moment operators by @MohammadShakiba in #229
• Bug fix for step 2 file saving and extension of states Slater determinants in step 3 by @MohammadShakiba in #233

New Contributors

• @foxtran made their first contribution in #224
• @SpringDabao made their first contribution in #231

Full Changelog: v5.8.0...v5.8.1

Libra v5.8.0: F-tracking and simplified NAC phase correction

The main changes

• The new F-tracking and simplified NAC phase correction are added and tested (the main reason for this release)

• Libra/MOPAC interface is developed but is yet to be demonstrated;

• QTSH is implemented but is yet to be demonstrated

• A critical bugfix in the step3 of Libra/cp2k interface - to possibly help solve the sudden jump problems we have observed recently

• The documentation of the main function in libra_py.dynamics.tsh.compute is updated and is now consistent with the parameters of the dyn_control_params class.

• Surface hopping in diabatic representation is added and is being tested by Daeho Han; within this development, new variable to hold active diabatic state indices for all trajectories are added. Several ways of computing diabatic populations are added: based on counting trajectories and on transformation of adiabatic SE or SH populations.

• Added auxiliary function to determine the active space selection in step3 of Libra/cp2k interface.

More formal changelog:

• Update QTSH by @DaehoHan in #212
• Bug fixes for ML workflow, step3, CP2K methods and data reading for BLLZ by @MohammadShakiba in #213
• Added an auxiliary function to step 3 for generating new active spaces based on the number of occupied and unoccupied orbitals by @MohammadShakiba in #214
• Reuse the rep_sh param to consider hops in the diabatic representation by @DaehoHan in #215
• Bug fixes for step3 many-body by @MohammadShakiba in #216

Full Changelog: v5.7.1...v5.8.0

Libra v5.7.1

Full Changelog: v5.7.0...v5.7.1

Libra v5.7.0

The major additions

• the new FSSH-3 methodology is implemented
• the FSSH-2 of Araujo et al. is implemented (with slight changes compared to the published version, but likely this is what was intended)
• added Jasper-Truhlar criterion of velocity reversal on frustrated hops
• added MD trajectory alignment function/script which processes the MD trajectory to remove the center of mass translation and the overall rotation of the molecule as whole (this is a Python re-interpretation of the Fortran code found in the auxiliary tools of NWChem)
• added a number of published spin-boson (and their many-state generalization) models withing the GLVC (generalized linear vibronic coupling models)
• implemented the Ohmic and Drude-Lorentz baths discretizations
• implemented a correct way of computing SH-based diabatic populations of states
• revised the way to initialize adiabatic states when the initial conditions are chosen in the diabatic representation
• added a number of matrix decompositions and linear equations solvers (based on matrix decompositions) from Eigen 3 code
• fixed bugs in sum_col and sum_row functions of generic matrix class
• significantly accelerated calculations of the matrix of the SD overlaps but using numpy methods in step3 module of the NBRA workflow (see below)
• implemented a lot of the functions and workflow for the ML-based prediction of KS Hamiltonians (see below)
• ongoing work on clarifying the MFSD (see below)

Auto-generated updates

• Update MFSD by @DaehoHan in #207
• Use act_states for saving the reference state of MFSD by @DaehoHan in #208
• Kohn-Sham Hamiltonian mapping with machine-learning first version by @MohammadShakiba in #209
• Revision of step3 and high-throughput implementation of KS ML map approach by @MohammadShakiba in #210

Full Changelog: v5.6.0...v5.7.0

v5.6.0

Final version of the XF-based methods (SHXF, MQCXF, and MFXF), coming along with the manuscript submission.

Major implementation was done already in the previous implementations. The present version ensures the consistency of some underlying transformation.

What's Changed

• XF propagations for the LD scheme by @DaehoHan in #200
• New functions in data_read and molden_methods by @MohammadShakiba in #201
• Update the XF algorithms by @DaehoHan in #202
• Fixing time propagation in XF by @DaehoHan in #204
• Fix the reordering of phase gradients by @DaehoHan in #205
• Elaborate on the comments about the td widths by @DaehoHan in #206

Full Changelog: v5.5.0...v5.6.0

Libra with TC-NBRA, MASH, FSSH2, revDISH, revised TSH and Ehrenfest, phase-corrected exact calculations

1. Structural changes and paradigm changes

• Restructured the libra_py library to set all the package-specific modules into a separate sub-library. Adapted importing
  libraries based on packages folder

• Simplified the interface of hop proposal, hop acceptance, and hop handling functions, as well as dish - these all
  are now taking the dyn_variables input rather than individual variables of all kinds

• Moved DISH coherence time updates inside dish function, added other decoherence options although they are not doing anything - just for completeness

2. New major capabilities

• [src/nHamiltonian and src/dyn]: The phase/state-consistency transformations (a.k.a local diabatization transformations)
  are now applied directly to element of the nHamiltonian object right after the new diabatic-to-adiabatic transformation is computed
  they are removed right before re-computing the time-overlaps at the next dynamical step. This way, the Hamiltonian properties
  are well-behaved and can be used both the TSH and Ehrenfest methods. This makes the Ehrenfest method conserve energy even in the adiabatic
  basis when NACs are used, as well as using the NAC-based integrators in the TD-SE integration of the TSH methods. This is a very
  critical change that hopefully makes the current implementation more reliable and robust than before.

• [src/dyn]: added themrally-correct NBRA (TC-NBRA) approach

• [src/dyn]: initial implementations of the Exact Factorization (XF) and mixed quantum-classical XF (MQCXF) methods

• [src/dyn]: Implemented MASH scheme

• [src/dyn]: Implemented FSSH2 scheme of Leonardo Araujo

• [src/dyn]: A new implementation of the DISH method, it is suitable for NBRA workflow too

• [src/dyn/wfcgrid2]: Added a phase-consistency correction to the diabatic-to-adiabatic transformation matrices computed at all grid points.
  This change is important since otherwise the kinetic energy calculations won't converge with dx due to highly-oscillatory behavior of the
  wavefunction in regions of strong nonadiabaticity. With this correction, the energy conservation is now much more robust and the convergence
  of kinetic energy w.r.t. the grid's dx is achieved. The wavefunctions are well-behaved too.

• [src/math_meigen]: Added Cholesky decomposition of real matrices

• [libra_py.models]: Added Ferretti Hamiltonian

• [src/dyn]: added Voronoi tesselaiton scheme and initial conditions sampling based on it

• [libra_py.dynamics.exact]: Added a new capability to the exact propagation function to save the wavefunction snapshots into files for their
  later plotting and animation. Updated the corresponding functions' documentation.

• [libra_py.packages.cp2k.methods]: Added analysis function for pdos, exc analysis, energy vs time to CP2K methods

3. Improvements and new minor capabilities

Dynamics

• Made the velocity rescaling happening only if the initial and final states are different

• Added the option to save the derivative coupling vectors along the trajectory

CP2K and NBRA

• Fixed the cp2k input generator script so that the calculations are more robust, correct, and lead to convergences

• Added new functionality to CP2K input generator for hybrid functionals

• Updated CP2K input generator

• Added new functions for computing MO coefficients + description of functions

• Added "restart_file" parameter for step_2. It is useful for big systems to have the initial guess of SCF orbitals

• Added isUKS implementation of open-shell systems. In Step3 of cp2k interacing-code, modified some functions to
  account for systems with different numbers of electrons in alpha and beta channels.

QTSH

• implemented an auxiliary function needed in kinematic momentum calculations for QTSH

GWP

• added derivatives of the GWP functions, in a somewhat different style

4. Bug fixes and documentation

src/dyn

• Fixed the bug with the velocity rescaling of only the quantum nuclear DOFs

• Fixed some bug that was breaking even normal FSSH, modified interface of the hop acceptance function to give a bit more flexibility

src/nHamiltonian

• Fixed a bug in the copy_content function of the nHamiltonian class where it would copy diabatic time-overlap into the
  adiabstic one, also added new functions to transform the elements of the nHamiltonian class according to certain
  transformation matrix, there are several kinds of such transformations with the same matrix - forward,backward, explicit, implicit or normalizing

DISH

• fixed a bug in the existing implementation of the DISH method

QTAG

• Adding a careful documentation and somewhat revising the interfaces of the QTAG functions, added new auxiliary ones

Models

• Fixed a bug in Holstein_gen function that would create an incorrect size of the first derivatives matrix

CP2K

• Added some documentation in the cp2k input generation module

• Fixed reading of TDDFT data in CP2K v23 - a very important fix, because it sometimes led to strange
  energies, especially of the ground state.

MFSD

• Fixed the implementation of the Shwartz decoherence times, also included the options to account for the local diabatization
  approximation in computing MF forces, added some documentation on the related functions, fixed some bugs in MFSD -
  the effective NAC calculations, momentum rescaling. The momentum rescaling and corresponding Hamiltonian update
  functions are also added in the main dynamics module for MFSD. Fixed more bugs in the mfsd code - the calculations of the
  Ehrenfest energies was not done correctly. Also, fixed the generic code for computing Ehrenfest energies - need to split by the trajectories

dynamics_plotting and data_visualize

• updated the decomentation of the dynamics_plotting function that plots surface and fixed a bug of not having the
  output directory to store figures produced

• Revised dynamics_plotting and data_visualize modules, added some documentation, added new member functions to the dyn_variables class

step2 of NBRA

• Fixed the reindexing function for isUKS=True

step3 of NBRA

• Debugging and revisiting mapping functions for Slater determinant calculations of NACs
  Added new mapping module with fully revised math and simplified interface

DFTB+

• Fixed some functions in DFTB+ package for it to be used in current NA-MD procedures, added documentation,
  got rid of the critical params, replaced them by default onese, fixed a minor bug in the dftb run_step2 function
  so the overlaps are now correct, changed the number of result objects returned by the do_step function

• Fixed the DFTB+ methods for reading time-overlap matrices - made them more robust to the known problem of having NaN
  and wrong values in the off-diagonal blocks of the super-molecule overlap matrix calculations

FT

• Updated the documentation of the ft2 function in the ft module

5. Cleaning up

• Removed deprecated dynamics tutorials

• Removed the DFTB time-overlap calculation tutorials. Moved the tutorial to the Tutorials_Libra repo and revised it

• Removed excessive output from libint2 code

• Cleaned up some commented and unnecessary code in the Dynamics.cpp and related files

• Revised the LZ workflow, removed deprecated or obsolete functionality and keywords

• Removed the examples of ACF and FT calculations. Now moved to the Tutorials_Libra repository