Yambopy tutorial: Yambo databases - Revision history

FulvioPaleari: /* Exciton intro 1: read and sort data */

2026-03-13T15:28:55Z

Exciton intro 1: read and sort data

← Older revision		Revision as of 15:28, 13 March 2026
Line 140:		Line 140:
	$ yambopy exc-sort --save BSE_saves/YAMBO_saves/SAVE -J BSE_saves/BSE_databases --iqpt 1		$ yambopy exc-sort --save BSE_saves/YAMBO_saves/SAVE -J BSE_saves/BSE_databases --iqpt 1

	Recall that that the path given <code>--save</code> must be the directory that contains the <code>ns.db1</code> yambo database (usually called... <code>SAVE</code>). The path given to <code>-J</code> must be the directory that ~~cotains~~ the results of the BSE calculation, namely the <code>ndb.BS_diago_Q1</code> file.		Recall that that the path given to <code>--save</code> must be the directory that contains the <code>ns.db1</code> yambo database (usually called... <code>SAVE</code>). The path given to <code>-J</code> must be the directory that contains the results of the BSE calculation, namely the <code>ndb.BS_diago_Q1</code> file. The final argument is the center-of-mass momentum of the exciton. In a standard absorption calculation, you only need the first Q-point which describes vertical electronic transitions. However, if you calculate the exciton dispersion, you will produce a <code>ndb.BS_diago_QN</code> at each momentum index N that you selected for the yambo BSE calculation.
	This should produce the <code>o-BSE_databases.exc_qpt1_sorted_E.dat</code> and <code>o-BSE_databases.exc_qpt1_sorted_I.dat</code> output files for you to inspect. These are very useful as they allow for identification of degenerate states and degree of optical activity. You will see that in our system most states are doubly degenerate, a byproduct of crystal symmetry. This is an updated version of the ypp exciton analysis that you can find [[How to analyse excitons#Sort the excitonic eigenvalues\|here]].
			This command should produce the <code>o-BSE_databases.exc_qpt1_sorted_E.dat</code> and <code>o-BSE_databases.exc_qpt1_sorted_I.dat</code> output files for you to inspect. These are very useful as they allow for identification of degenerate states and degree of optical activity. You will see that in our system most states are doubly degenerate, a byproduct of crystal symmetry. This is an updated version of the ypp exciton analysis that you can find [[How to analyse excitons#Sort the excitonic eigenvalues\|here]].

	=== Exciton intro 2: symmetry analysis and wavefunction plot in real space ===		=== Exciton intro 2: symmetry analysis and wavefunction plot in real space ===

FulvioPaleari: /* Exciton intro 1: read and sort data */

2026-03-13T15:25:59Z

Exciton intro 1: read and sort data

← Older revision		Revision as of 15:25, 13 March 2026
Line 140:		Line 140:
	$ yambopy exc-sort --save BSE_saves/YAMBO_saves/SAVE -J BSE_saves/BSE_databases --iqpt 1		$ yambopy exc-sort --save BSE_saves/YAMBO_saves/SAVE -J BSE_saves/BSE_databases --iqpt 1

			Recall that that the path given <code>--save</code> must be the directory that contains the <code>ns.db1</code> yambo database (usually called... <code>SAVE</code>). The path given to <code>-J</code> must be the directory that cotains the results of the BSE calculation, namely the <code>ndb.BS_diago_Q1</code> file.
	This should produce the <code>o-BSE_databases.exc_qpt1_sorted_E.dat</code> and <code>o-BSE_databases.exc_qpt1_sorted_I.dat</code> output files for you to inspect. These are very useful as they allow for identification of degenerate states and degree of optical activity. You will see that in our system most states are doubly degenerate, a byproduct of crystal symmetry. This is an updated version of the ypp exciton analysis that you can find [[How to analyse excitons#Sort the excitonic eigenvalues\|here]].		This should produce the <code>o-BSE_databases.exc_qpt1_sorted_E.dat</code> and <code>o-BSE_databases.exc_qpt1_sorted_I.dat</code> output files for you to inspect. These are very useful as they allow for identification of degenerate states and degree of optical activity. You will see that in our system most states are doubly degenerate, a byproduct of crystal symmetry. This is an updated version of the ypp exciton analysis that you can find [[How to analyse excitons#Sort the excitonic eigenvalues\|here]].

FulvioPaleari at 09:34, 10 March 2026

2026-03-10T09:34:12Z

← Older revision		Revision as of 09:34, 10 March 2026
Line 266:		Line 266:

	[[File:Absalpha.png\|Yambo alpha_2D tutorial plot\|700px]]		[[File:Absalpha.png\|Yambo alpha_2D tutorial plot\|700px]]

	~~=== Command line: importing electron-phonon matrix elements ===~~
	~~You may have seen how to calculate and import electron-phonon matrix elements in yambo in the [[Electron Phonon Coupling\|electron-phonon tutorial]].~~

	~~With Yambopy, we can generate a yambo SAVE folder and import the matrix elements with a single command.~~
	~~Typing~~
	~~$yambopy gkkp~~
	~~will print the necessary documentation:~~
	~~Produce a SAVE folder including elph_gkkp databases~~

	~~Arguments are:~~
	~~-nscf, --nscf_dir -> <Optional> Path to nscf save folder~~
	~~-elph, --elph_dir -> Path to elph_dir folder~~
	~~-y, --yambo_dir -> <Optional> Path to yambo executables~~
	~~-e, --expand -> <Optional> Expand gkkp databases~~

	The necessary quantum espresso databases are stored in <code>ELPH_SAVES/QE_SAVES/hBN.save</code> (nscf calculation) and <code>ELPH_SAVES/QE_SAVES/elph_dir</code> (matrix elements from the dfpt calculation). For this tutorial we also need to expand the electron-phonon matrix elements to the full Brillouin zone. Since this is a different calculation with respect to the previous section, please generate this SAVE in a different directory than the one you used for the previous SAVE, which should be the current directory.
	~~For example:~~
	~~$mkdir yambo-with-elph~~
	~~$cd yambo-with-elph~~

	~~Now we can run yambopy as in the instructions:~~
	~~$yambopy gkkp -nscf ../ELPH_saves/QE_saves/hBN.save -elph ../ELPH_saves/QE_saves/elph_dir --expand~~
	~~This should generate a yambo SAVE folder which contains the <code>ndb.elph_gkkp_expanded*</code> databases.~~

	~~=== Electron-phonon intro: plots of el-ph matrix elements on k-BZ and q-BZ ===~~
	~~In this section we will use the script <code>elph_plot.py</code> and read the electron-phonon databases that you generated in the previous section.~~

	~~In order to read the <code>ndb.elph_gkkp_expanded*</code> databases in python we use the Yambopy class <code>YamboElectronPhononDB</code>, which can be instanced like this:~~
	~~yelph = YamboElectronPhononDB(ylat,folder_gkkp='path/to/elph/folder',save='path/to/SAVE')~~
	~~(notice that it requires a previous instance of <code>YamboLatticeDB</code>).~~

	Now, the <code>yelph</code> object contains phonon frequencies, phonon eigenvectors, qpoint information and, of course, the electron-phonon matrix elements g_{nm\nu}(k,q) where n, m are electron band states, \nu is a phonon branch, and k and q are the electronic and transfer momenta.

	~~We can print the docstring of the <code>YamboElectronPhononDB</code> class with~~
	~~print(yelph.__doc__)~~
	~~to get an idea of the information stored and of its capabilities.~~

	~~Now check the <code>elph_plot.py</code> script. You will see that it performs two plots:~~
	* Plot of \|g(k)\| in the k-BZ for selected n,m,\nu and q [<code>Kspace_Plot=True</code>].
	* Plot of \|g(q)\| in the q-BZ for selected n,m,\nu and k [<code>Qspace_Plot=True</code>].

	~~You can change the electronic, phononic and momentum indices to see what happens.~~

	~~[[File:Elph hbn.jpg\|YamboElectronPhononDB plot from yambopy tutorial\|500px]]~~


	==Links==		==Links==

FulvioPaleari: /* Command line: generating the Yambo SAVE */

2026-03-09T19:12:58Z

Command line: generating the Yambo SAVE

← Older revision		Revision as of 19:12, 9 March 2026
Line 28:		Line 28:
	analysebse -> Study the convergence of BSE calculations.		analysebse -> Study the convergence of BSE calculations.
	analysegw -> Study the convergence of GW calculations by looking at the change in band-gap value.		analysegw -> Study the convergence of GW calculations by looking at the change in band-gap value.
	plotexcitons -> Plot excitons calculation		plotexcitons -> Plot excitons calculation.
	addqp -> Add corrections from QP databases.		addqp -> Add corrections from QP databases.
	mergeqp -> Merge QP databases		mergeqp -> Merge QP databases.
	save -> Produce a SAVE folder		save -> Produce a SAVE folder.
	gkkp -> Produce a SAVE folder including elph_gkkp databases		gkkp -> Produce a SAVE folder including elph_gkkp databases.
	bands -> Script to produce band structure data and visualization from QE.		bands -> Script to produce band structure data and visualization from QE.
	serial -> Script to update serial numbers of yambo ndb.* databases in order to import them to new calculations.		serial -> Script to update serial numbers of yambo ndb.* databases in order to import them to new calculations.

FulvioPaleari: /* Lattice intro: plot k-point coordinates in IBZ/BZ */

2026-03-09T19:09:35Z

Lattice intro: plot k-point coordinates in IBZ/BZ

← Older revision		Revision as of 19:09, 9 March 2026
Line 67:		Line 67:
	We are now going to read it in python by using the Yambopy class <code>YamboLatticeDB</code>, which can be instanced like this:		We are now going to read it in python by using the Yambopy class <code>YamboLatticeDB</code>, which can be instanced like this:

	from yambopy import *		from yambopy import YamboLatticeDB
	ylat = YamboLatticeDB.from_db_file(filename="PATH/TO/SAVE/ns.db1")		ylat = YamboLatticeDB.from_db_file(filename="PATH/TO/SAVE/ns.db1")
	(remember to edit the variable <code>save_path</code> in order to point at your yambo SAVE).		(remember to edit the variable <code>save_path</code> in order to point at your yambo SAVE).

FulvioPaleari: /* Command line: generating the Yambo SAVE */

2026-03-09T19:09:00Z

Command line: generating the Yambo SAVE

← Older revision		Revision as of 19:09, 9 March 2026
Line 24:		Line 24:
	yambopy v0.7		yambopy v0.7
	Available commands are:		Available commands are:

	plotem1s -> Plot em1s calculation.		plotem1s -> Plot em1s calculation.
	analysebse -> Study the convergence of BSE calculations.		analysebse -> Study the convergence of BSE calculations.
Line 47:		Line 47:
	By typing in one of these, additional information about how to run the commands will be printed, e.g.:		By typing in one of these, additional information about how to run the commands will be printed, e.g.:
	$yambopy save		$yambopy save

	Produce a SAVE folder		Produce a SAVE folder

FulvioPaleari at 19:08, 9 March 2026

2026-03-09T19:08:25Z

← Older revision		Revision as of 19:08, 9 March 2026
Line 3:		Line 3:
	In particular we will take a look at:		In particular we will take a look at:
	* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).		* Lattice geometry data (Yambo database: <code>ns.db1</code>, Yambopy class: <code>YamboLatticeDB</code>).
	* Electron-phonon matrix elements (Yambo databases: <code>ndb.elph_gkkp*</code>, Yambopy class: <code>YamboElectronPhononDB</code>).
	* Dipole matrix elements (Yambo databases: <code>ndb.dipoles</code>, Yambopy class: <code>YamboDipolesDB</code>).		* Dipole matrix elements (Yambo databases: <code>ndb.dipoles</code>, Yambopy class: <code>YamboDipolesDB</code>).
	* Exciton wavefunctions~~, energy~~ and spectra (Yambo databases: <code>ndb.BS_diago_Q*</code>, Yambopy class: <code>YamboExcitonDB</code>).		* Exciton energies, symmetries, wavefunctions and spectra (Yambo databases: <code>ndb.BS_diago_Q*</code>, Yambopy class: <code>YamboExcitonDB</code>).

	We will also check the command line instructions to quickly generate yambo SAVE folders.		We will also check the command line instructions to quickly generate yambo SAVE folders.
Line 23:		Line 22:
	$yambopy		$yambopy
	which will print the output		which will print the output
	yambopy		yambopy v0.7
	Available commands are:		Available commands are:

	plotem1s -> Plot em1s calculation		plotem1s -> Plot em1s calculation.
	analysebse -> ~~Using ypp, you can study~~ the convergence of BSE calculations ~~in 2 ways:~~		analysebse -> Study the convergence of BSE calculations.
	analysegw -> Study the convergence of GW calculations by looking at the change in band-gap value.		analysegw -> Study the convergence of GW calculations by looking at the change in band-gap value.
	plotexcitons -> Plot excitons calculation		plotexcitons -> Plot excitons calculation
Line 36:		Line 35:
	bands -> Script to produce band structure data and visualization from QE.		bands -> Script to produce band structure data and visualization from QE.
	serial -> Script to update serial numbers of yambo ndb.* databases in order to import them to new calculations.		serial -> Script to update serial numbers of yambo ndb.* databases in order to import them to new calculations.
	~~test~~ -> ~~Run yambopy tests~~		gwsubspace -> Script to calculate off-diago corrections of yambo ndb.QP databases in order to plot band structure.
			phinp -> Script to update the explicit list of q-points in a ph input file (ldisp=.false., qplot=.true.).
			convert -> Script to convert RL number in Ry energy units using ndb.gops.
			bsesize -> Script to calculate the expected BSE kernel size, in GB, to be loaded by each MPI task.
			l2y -> Calculate gauge-invariant electron-phonon matrix elements with LetzElPhC and convert them into Yambo format.
			exc-irrep -> Script to get the irreducible representation labels for excitonic states. [-h for help]
			exc-wf -> Real space exciton wf for either fixed hole/electron. [-h for help]
			exc-sort -> Script to sort excitonic states according to energies and intensities. [-h for help]

	For this tutorial, we will need the <code>save</code> and <code>gkkp</code> options.		For this tutorial, we will need the <code>save</code> and <code>gkkp</code> options.

FulvioPaleari: /* Lattice intro: plot k-point coordinates in IBZ/BZ */

2026-03-09T19:01:32Z

Lattice intro: plot k-point coordinates in IBZ/BZ

← Older revision		Revision as of 19:01, 9 March 2026
Line 85:		Line 85:
	Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.		Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.

	* bohr^-1 (atomic units): <code>YamboLatticeDB.car_kpoints2.pi</code>. Divide by the bohr to angstrom ~~convertion~~ factor to obtain angs^-1		* bohr^-1 (atomic units): <code>YamboLatticeDB.car_kpoints2.pi</code>. Divide by the bohr-to-angstrom conversion factor to obtain angs^-1
	* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLatticeDB.car_kpoints2.pi</code> (same as above).		* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLatticeDB.car_kpoints2.pi</code> (same as above).
	* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLatticeDB.car_kpoints*YamboLatticeDB.alat[0]</code>.		* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLatticeDB.car_kpoints*YamboLatticeDB.alat[0]</code>.

FulvioPaleari: /* Lattice intro: plot k-point coordinates in IBZ/BZ */

2026-03-09T18:59:51Z

Lattice intro: plot k-point coordinates in IBZ/BZ

← Older revision		Revision as of 18:59, 9 March 2026
Line 85:		Line 85:
	Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.		Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.

	* ~~'''~~bohr^-1~~'''~~ (atomic units): <code>~~YamboLattceDB~~.car_kpoints2.pi</code>. Divide by the bohr to angstrom convertion factor to obtain angs^-1		* bohr^-1 (atomic units): <code>YamboLatticeDB.car_kpoints2.pi</code>. Divide by the bohr to angstrom convertion factor to obtain angs^-1
	* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>~~YamboLattceDB~~.car_kpoints2.pi</code> (same as above).		* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLatticeDB.car_kpoints2.pi</code> (same as above).
	* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>~~YamboLattceDB~~.car_kpoints*YamboLatticeDB.alat[0]</code>.		* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLatticeDB.car_kpoints*YamboLatticeDB.alat[0]</code>.
	* Internal yambo units (<code>[iku]</code> in yambo outputs): <code>~~YamboLattceDB~~.iku_kpoints</code>		* Internal yambo units (<code>[iku]</code> in yambo outputs): <code>YamboLatticeDB.iku_kpoints</code>
	* Fractional coordinates (<code>[rlu]</code> in yambo, <code>cryst. coord.</code> in QE): <code>YamboLatticeDB.red_kpoints</code>.		* Fractional coordinates (<code>[rlu]</code> in yambo, <code>cryst. coord.</code> in QE): <code>YamboLatticeDB.red_kpoints</code>.

FulvioPaleari: /* Lattice intro: plot k-point coordinates in IBZ/BZ */

2026-03-09T18:58:55Z

Lattice intro: plot k-point coordinates in IBZ/BZ

← Older revision		Revision as of 18:58, 9 March 2026
Line 82:		Line 82:

	'''What about the units?'''		'''What about the units?'''

	Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.		Below we report the relation between units used in Yambo, Quantum Espresso, and Yambopy.

	* bohr^-1 (atomic units): <code>YamboLattceDB.car_kpoints2.pi</code>. Divide by the bohr to angstrom convertion factor to obtain angs^-1		* '''bohr^-1''' (atomic units): <code>YamboLattceDB.car_kpoints2.pi</code>. Divide by the bohr to angstrom convertion factor to obtain angs^-1
	* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLattceDB.car_kpoints2.pi</code> (same as above).		* Yambo cartesian units (<code>[cc]</code> in Yambo outputs): <code>YamboLattceDB.car_kpoints2.pi</code> (same as above).
	* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLattceDB.car_kpoints*YamboLatticeDB.alat[0]</code>.		* QE cartesian units (<code>[cart. coord. in units 2pi/alat]</code> in QE outputs): <code>YamboLattceDB.car_kpoints*YamboLatticeDB.alat[0]</code>.