pyQME is a Package for Open Quantum System Dynamics and spectroscopies simulations in the exciton framework, written in Python 3.
The terms for using, copying, modifying, or distributing this code are specified in the file LICENSE
Piermarco Saraceno ([email protected])
Lorenzo Cupellini ([email protected])
Dipartimento di Chimica e Chimica Industriale, Via G. Moruzzi 13, I-56124, Pisa (PI), Italy
When installing pyQME all the dependencies are included, however in case you have specific requirements for the pyQME installation, you may want to install pyQME separately, before installing pyQME.
An environment with any version of Python 3 is recommended. You can create it with conda, virtualenv, or pyenv.
For example, with conda run the following code:
conda create -n pyQME-env python=3.7conda activate pyQME-envFrom the pyQME folder, you can install the module with pip:
pip install .You can install pyQME locally with:
pip install -e .so that possible code changes take effect immediately on the installed version.
You may want to look at the examples. The package doesn't come with a Command Line Interface (CLI), so it must be used via Python (or any hosting platform, such as Jupyter Lab).
Spectral density are created (generally) from a frequency axis and the spectral density.
For example,
# freq_axis is a 1D numpy array of size N
# SD is a 1D numpy array of size N
SD_obj = SpectralDensity(freq_axis,SD,temperature=298)
Relaxation tensors are created (generally) from a Hamiltonian and a spectral density object.
For example, to create a Real Redfield tensor,
# H is a NxN numpy array
# SD_obj is a SpectralDensity object
redf = RedfieldTensor(H,SD_obj,initialize=True)
relaxation_tensor = redf.get_tensor()
The same procedure is valid for the Relaxation tensors in the double exciton manifold, used for pump-probe calculations.
For example,
# H is a NxN numpy array
# SD_obj is a SpectralDensity object
redf_double = RedfieldTensorDouble(H,SD_obj)
Once the Relaxation tensor object has been created, it can be used to propagate a density matrix.
For example,
# time_axis_ps is a 1D Numpy array of size T (in picoseconds)
# rho_0 is the density matrix (NxN numpy array) at the beginning of the simulation in the exciton basis
rho_t = redf.propagate(rho0,units='ps',basis='exciton')
# rho_t is the propagated density matrix (TxNxN numpy array) in the exciton basis
The simulation of absorption and fluorescence spectra takes as input the relaxation tensor object and the transition dipoles.
For example, to simulate an absorption spectrum:
# dipoles is a Nx3 numpy array
lin_spec_obj = SecularLinearSpectraCalculator(redf)
freq_axis,OD = lin_spec_obj.calc_OD(dipoles)
# freq_axis and OD are 1D numpy arrays of size W
The simulation of pump-probe spectra takes as input the relaxation tensors object in the single and double exciton-manifold, the transition dipoles and the populations.
For example:
# dipoles is a Nx3 numpy array
# pop_t_exc is a TxN numpy array (diagonal of the density matrix in the exciton basis)
pump_probe_obj = PumpProbeSpectraCalculator(redf,redf_double)
pump_probe_obj.calc_components_lineshape(dipoles=dipoles)
freq_axis,GSB,SE,ESA,PP = spectrum_obj.get_pump_probe(pop_t_exc)
# freq_axis is a numpy array of size W
# GSB,SE,ESA,PP are numpy arrays of shape TxW
The frequency axis, the time axis of the spectral density, the exciton Hamiltonian and the EET rates must be in
The time axis for the density matrix propagation can be either in cm or in ps (see the "units" argument of the method /pyQME/tensors/relaxation_tensor/RelTensor.propagate)
The electric transition dipoles must be in Debye (x,y,z components).
The temperature must be in Kelvin.
The absorption and pump-probe spectra are returned in optical density units (include_fact=True, or in dipole^2 units (i.e, units_of_dypole^2, for example Debye^2) if include_fact=False. In this latter case the integral of the spectra is the dipole strength = sum_ix (mu_ix)^2 (absorption), or one (fluorescence).
Some useful conversion factors and physical constants in pyQME/utils.py.
- The frequency and time axes must be sorted in ascending order.
- The spectral density used as input must not be divided by the frequency axis.
- The spectral density used as input must contain the
$\pi$ factor. To be sure about it, you can check that SDobj.Reorg corresponds to the expected reorganization energy. - The time axis used for the lineshape functions and for the spectra calculation must be defined in the spectral density class. The time axis is automatically optimized in the
SpectralDensityobject, but you can always define it manually using thetimeoption of theSpectralDensityobject, or itsset_timemethod. - If you are propagating the density matrix using the "eig" mode of relaxation_tensor.propagate, be sure that the Liouvillian of your system (relaxation_tensor.get_Liouv()) is diagonalizable. For this, you can also compare the density matrix propagated using the "exp" mode with that propagated using the "eig", which is in general faster.
The indices convention employed in this code is the following:
- i,j,k,l: site basis (single excitations)
- a,b,c,d: single-exciton manifold
- u,v: site basis (double excitations)
- q,r,s,t: double-exciton manifold
- Z: spectral density
We recommend making changes in a branch of your local version. Make sure that your main branch is up to date with the upstream:
git pull upstream mainIf you feel your work is completed and want to merge it with the main branch of pyQME, you can
make a merge request and ask for a review of your work.
If, when contributing with some feature, you want to write some unit test for it, we are all super happy.
When using pyQME, please cite the following paper.
Saraceno, P.; Sl ama, V.; Cupellini, L. The Journal of Chemical Physics 2023,159, 184112. https://doi.org/10.1063/5.0170295
Redfield theory:
REDFIELD, A. In Advances in Magnetic Resonance, Waugh, J. S., Ed.; Advances in Magnetic and Optical Resonance, Vol. 1; Academic Press: 1965, 1–32. https://doi.org/10.1016/B978-1-4832-3114-3.50007-6
Renger, T.; Marcus, R. A. The Journal of Chemical Physics 2002, 116, 9997–10019. https://doi.org/10.1063/1.1470200
Förster theory:
F ̈orster, T. Journal of Biomedical Optics 2012, 17, 011002. https://doi.org/10.1117/1.JBO.17.1.011002
Modified Redfield theory:
Zhang, W. M.; Meier, T.; Chernyak, V.; Mukamel, S. The Journal of Chemical Physics 1998, 108, 7763–7774. https://doi.org/10.1063/1.476212
Hwang-Fu, Y.-H.; Chen, W.; Cheng, Y.-C. Chemical Physics 2015, 447, 46–53. https://doi.org/10.1016/j.chemphys.2014.11.026
Redfield-Förster theory:
Yang, M.; Damjanovi ́c, A.; Vaswani, H. M.; Fleming, G. R. Biophysical Journal 2003, 85, 140–158. https://doi.org/10.1016/S0006-3495(03)74461-0
Linear spectra:
Gelzinis, A.; Abramavicius, D.; Valkunas, L. The Journal of Chemical Physics 2015, 142, 154107. https://doi.org/10.1063/1.4918343
Cupellini, L.; Lipparini, F.; Cao, J. The Journal of Physical Chemistry B 2020, 124, 8610–8617. https://doi.org/10.1021/acs.jpcb.0c05180
Nothling, J. A.; Mancal, T.; Kruger, T. P. J. The Journal of Chemical Physics 2022, 157, 095103. https://doi.org/10.1063/5.0100977
Ma, J., & Cao, J. (2015). Journal of Chemical Physics, 142(9). https://doi.org/10.1063/1.4908599
Circular Dichroism: Jurinovich, S., Cupellini, L., Guido, C. A., & Mennucci, B. (2018). Exat: Excitonic analysis tool. Journal of Computational Chemistry, 39(5), 279–286. https://doi.org/10.1002/jcc.25118
Pump-probe:
Novoderezhkin, V. I.; Doust, A. B.; Curutchet, C.; Scholes, G. D.; van Grondelle, R. Biophysical Journal 2010, 99, 344–352. https://doi.org/10.1016/j.bpj.2010.04.039
Renger, T.; Marcus, R. A. The Journal of Chemical Physics 2002, 116, 9997–10019. https://doi.org/10.1063/1.1470200
Double-exciton manifold:
Saraceno, P.; Slama, V.; Cupellini, L. The Journal of Chemical Physics 2023,159, 184112. https://doi.org/10.1063/5.0170295