PAOFLOW.Transport#

Classes#

Transport

User-facing transport orchestrator with direct-argument APIs.

Module Contents#

class PAOFLOW.Transport.Transport(data_controller)[source]#

User-facing transport orchestrator with direct-argument APIs.

Parameters:

data_controller (DataController) – Shared PAOFLOW DataController used by transport preparation stages.

Variables:

  • conductor_data (ConductorData or None) – Validated conductor input model populated by build_hamiltonian_blocks.

  • blc_blocks (dict[str, Any] or None) – Hamiltonian block operators populated by build_hamiltonian_blocks.

  • results (TransportResults or None) – Cached full-grid transport observables.

data_controller[source]#
conductor_data: PAOFLOW.transport.data.ConductorData | None = None[source]#
blc_blocks: dict[str, Any] | None = None[source]#
results: PAOFLOW.transport.results.TransportResults | None = None[source]#
configure_energy_grid(*, emin, emax, ne, delta, nk=(0, 0), smearing_type='lorentzian', delta_ratio=0.005, xmax=25.0, ne_buffer=1, energy_step=0.001, nx_smear=20000)[source]#

Configure the energy and k-grid integration settings.

Must be called before any full-grid observable computation.

Parameters:

  • emin (float) – Minimum energy in eV.

  • emax (float) – Maximum energy in eV.

  • ne (int) – Number of energy points.

  • delta (float) – Broadening parameter.

  • nk (list[int] or tuple[int, int], optional) – 2D k-grid dimensions. Default is (0, 0).

  • smearing_type (str, optional) – Smearing function: 'lorentzian' (default), 'gaussian', 'fermi-dirac'/'fd', 'methfessel-paxton'/'mp', or 'marzari-vanderbilt'/'mv'.

  • delta_ratio (float, optional) – Adaptive-smearing ratio. Default 5.0e-3.

  • xmax (float, optional) – Smearing cutoff in units of the broadening. Default 25.0.

  • ne_buffer (int, optional) – Number of energy points processed per buffered chunk. Default 1.

  • energy_step (float, optional) – Energy step used when building the smearing table. Default 0.001.

  • nx_smear (int, optional) – Number of samples in the precomputed smearing table. Default 20000.

configure_outputs(*, output_dir='./', work_dir='./', postfix='', write_kdata=False)[source]#

Configure output directory, file postfix, and optional operator outputs.

Parameters:

  • output_dir (str, optional) – Directory where transport output files are written.

  • work_dir (str, optional) – Working directory for transport assets.

  • postfix (str, optional) – String appended to default transport file names.

  • write_kdata (bool, optional) – If True, write k-resolved transmission and DOS to separate files.

configure_transport_options(*, formula='landauer', **options)[source]#

Configure the conductance formula and other transport options.

Parameters:

  • formula (str, optional) – Conductance formula. Supported values: 'landauer', 'generalized'. Default is 'landauer'.

  • **options (Any) – Additional formula-specific options forwarded to ConductorData.

define_partition(*, central_atoms='ALL', central_layers=None, left_lead_layers=None, right_lead_layers=None, transport_direction, layer_tolerance=1e-06)[source]#

Define a layer-based transport partition.

The partition is resolved immediately from PAOFLOW atom/order metadata into Hamiltonian block dimensions and orbital selectors. Users specify physical layers along transport_direction instead of PAO indices.

Parameters:

  • central_atoms (str, optional) – Central region atom selector. Currently only 'ALL' is supported.

  • central_layers (int or None, optional) – If provided, use this many layers from the start of the transport direction as the central region. This is useful for lead-only bulk calculations.

  • left_lead_layers (int or None, optional) – Number of layers at the start/end of the transport direction used to construct conductor lead and coupling blocks.

  • right_lead_layers (int or None, optional) – Number of layers at the start/end of the transport direction used to construct conductor lead and coupling blocks.

  • transport_direction ({'x', 'y', 'z'}) – Direction along which transport is computed.

  • layer_tolerance (float, optional) – Coordinate tolerance used to group atoms into layers.

configure_onsite_shifts(*, shift_L=0.0, shift_C=0.0, shift_R=0.0, shift_corr=0.0)[source]#

Configure rigid on-site energy shifts for lead/conductor alignment.

Parameters:

  • shift_L (float, optional) – Rigid on-site energy shifts (eV) applied to the left-lead, conductor, and right-lead blocks respectively. Default 0.0.

  • shift_C (float, optional) – Rigid on-site energy shifts (eV) applied to the left-lead, conductor, and right-lead blocks respectively. Default 0.0.

  • shift_R (float, optional) – Rigid on-site energy shifts (eV) applied to the left-lead, conductor, and right-lead blocks respectively. Default 0.0.

  • shift_corr (float, optional) – On-site energy shift (eV) applied to the correlation self-energy. Default 0.0.

configure_lead_convergence(*, niterx=200, transfer_thr=1e-07, nprint=20, nfailx=5, surface=False)[source]#

Configure the lead surface-Green’s-function transfer-matrix iteration.

Parameters:

  • niterx (int, optional) – Maximum number of lead transfer-matrix iterations. Default 200.

  • transfer_thr (float, optional) – Convergence threshold for the transfer-matrix iteration. Default 1.0e-7.

  • nprint (int, optional) – Iteration-progress print frequency. Default 20.

  • nfailx (int, optional) – Maximum number of allowed convergence failures. Default 5.

  • surface (bool, optional) – If True, run in surface mode (lead surface Green’s function only, skipping the right-lead self-energy). Default False.

configure_eigenchannels(*, do_eigenchannels=False, neigchnx=200000, do_eigplot=False, ie_eigplot=0, ik_eigplot=0)[source]#

Configure transmission eigenchannel decomposition and plotting.

Parameters:

  • do_eigenchannels (bool, optional) – If True, compute transmission eigenchannels. Default False.

  • neigchnx (int, optional) – Maximum number of eigenchannels to retain. Default 200000.

  • do_eigplot (bool, optional) – If True, write eigenchannel data for a chosen (energy, k) point.

  • ie_eigplot (int, optional) – Energy index to plot eigenchannels for (with do_eigplot).

  • ik_eigplot (int, optional) – k-point index to plot eigenchannels for (with do_eigplot).

build_hamiltonian_blocks(*, calculation_type='bulk', carriers='electrons', use_sym=False, do_overlap_transformation=False, ispin=0, debug=False, **block_options)[source]#

Build conductor Hamiltonian blocks from the defined partition.

Accepts only parameters required to construct Hamiltonian/overlap block objects after define_partition(). Energy-grid parameters (emin, emax, ne, delta), output paths, and optional operator outputs must be configured separately via configure_energy_grid(...), configure_outputs(...), and configure_transport_options(...).

Parameters:

  • calculation_type (str, optional) – Calculation mode: 'bulk' or 'conductor'.

  • carriers (str, optional) – Carrier type ('electrons' or 'phonons').

  • use_sym (bool, optional) – Apply time-reversal symmetry to reduce the k-point sampling.

  • do_overlap_transformation (bool, optional) – Apply the overlap-matrix orthogonalisation transformation.

  • ispin (int, optional) – Spin channel to use for spin-polarized inputs (0, 1, or 2).

  • debug (bool, optional) – If True, write human-inspectable debug artifacts during setup: the legacy .ham file, projectability.txt, and (when overlap is enabled) kovp.txt. Off by default.

  • **block_options (Any) – Additional block-construction options forwarded to ConductorData (for example self-energy file paths for generalized formulas).

Returns:

Block-operator mapping used by conductor self-energy and Green-function calculations. Also stored as self.blc_blocks.

Return type:

dict[str, Any]

Notes

A layer partition must be supplied beforehand via define_partition(). Optional physics tuning is applied through configure_onsite_shifts(), configure_lead_convergence(), and configure_eigenchannels(); energy/smearing via configure_energy_grid() and outputs via configure_outputs().

Sets self.conductor_data and self.blc_blocks as side effects. Calling this method a second time resets both for the new calculation.

compute_leads_self_energy(*, write=True, comm=MPI.COMM_WORLD)[source]#

Compute full-grid lead self-energies and write XML outputs.

Parameters:

  • write (bool, optional) – If True (default), write real-space self-energies to lead_L_sgm.xml and lead_R_sgm.xml.

  • comm (MPI.Comm, optional) – MPI communicator. Default is MPI.COMM_WORLD.

Returns:

(self_energy_L, self_energy_R) in real space, shape (ne, nrtot_par, dimC, dimC) each, or (None, None) if write is False.

Return type:

tuple[NDArray[np.complex128] or None, NDArray[np.complex128] or None]

compute_greens_functions(*, write=True, comm=MPI.COMM_WORLD)[source]#

Compute full-grid conductor Green’s functions and write XML output.

Parameters:

  • write (bool, optional) – If True (default), write real-space Green’s functions to greenf.xml.

  • comm (MPI.Comm, optional) – MPI communicator. Default is MPI.COMM_WORLD.

Returns:

Real-space conductor Green’s function, shape (ne, nrtot_par, dimC, dimC), or None if write is False.

Return type:

NDArray[np.complex128] or None

compute_transmission(*, comm=MPI.COMM_WORLD)[source]#

Compute full-grid transmission and write output files.

Parameters:

comm (MPI.Comm, optional) – MPI communicator. Default is MPI.COMM_WORLD.

Returns:

Transmission, shape (1 + neigchn, ne).

Return type:

NDArray[np.float64]

Notes

Writes conductance*.dat under the configured output directory.

compute_dos(*, comm=MPI.COMM_WORLD)[source]#

Compute full-grid DOS and write output files.

Parameters:

comm (MPI.Comm, optional) – MPI communicator. Default is MPI.COMM_WORLD.

Returns:

Density of states, shape (ne,).

Return type:

NDArray[np.float64]

Notes

Writes doscond*.dat under the configured output directory.

compute_current(*, bias_min, bias_max, nbias, mu_L, mu_R, sigma, comm=MPI.COMM_WORLD)[source]#

Compute current vs bias from the in-memory transmission and write output.

Requires that build_hamiltonian_blocks(...), configure_energy_grid(...), and configure_outputs(...) have already been called. Transmission is taken from the cached full-grid results; if not yet computed, the full-grid calculation runs here.

Parameters:

  • bias_min (float) – Minimum bias voltage in V.

  • bias_max (float) – Maximum bias voltage in V (must be greater than bias_min).

  • nbias (int) – Number of bias points (must be positive).

  • mu_L (float) – Left chemical-potential scaling coefficient; enters as \(\mu_L \cdot V\).

  • mu_R (float) – Right chemical-potential scaling coefficient; enters as \(\mu_R \cdot V\).

  • sigma (float) – Smearing width in eV for the Fermi-Dirac broadening (must be positive).

  • comm (MPI.Comm, optional) – Communicator used for work distribution. Default is MPI.COMM_WORLD.

Returns:

Current values aligned with the internally generated bias grid, shape (nbias,).

Return type:

NDArray[np.float64]

Notes

Writes current.dat as two columns V I under the configured output directory.