### Install TheoDORE

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

Clone the repository and install using pip. Alternatively, source the setpaths script for manual path configuration. Verify the installation with the -h flag.

```bash
# Clone with all submodules
git clone --recursive https://github.com/felixplasser/theodore-qc.git
cd theodore-qc

# Install (requires Python >= 3.6)
pip install .

# Or set paths manually without installing
source setpaths.bash   # bash
source setpaths.csh    # csh/tcsh

# Verify installation
theodore -h
```

--------------------------------

### DFT/MRCI Workflow Example

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Example workflow for running DFT/MRCI and generating density matrices for TheoDORE analysis.

```bash
mrci_serial < mrci.inp > mrci.out
cp mrci.refconf mrci2.inp
mrci_serial < mrci2.inp > mrci2.out
sed 's/orca/orca\n$dmat/' mrci2.inp > mrci2_dmat.inp
mrci_serial < mrci2_dmat.inp > mrci2_dmat.out
```

--------------------------------

### Install ORBKIT

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/installation.rst

Commands to build and install the ORBKIT package in-place within the TheoDORE distribution.

```bash
cd $THEODIR/external/orbkit
python3 setup.py build_ext --inplace
```

--------------------------------

### Source Environment Setup Script

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/installation.rst

Command to apply the environment variable settings from the setpaths.bash script to the current shell session.

```bash
source setpaths.bash
```

--------------------------------

### ADF Script Activation and Environment Setup

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Activate ADF scripts and set necessary environment variables for TheoDORE analysis.

```bash
. ~/adfrc.sh
export SCMLICENSE=/usr/license/adf/licenses/license.txt
export PYTHONPATH=$PYTHONPATH:/usr/license/adf/adf2016.101/scripting
```

--------------------------------

### Full dens_ana.in Example for Q-Chem TDDFT

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

This configuration file sets up a comprehensive Q-Chem TDDFT analysis, specifying input files, calculation types, fragment definitions, properties to compute, NTO analysis options, and output formatting. Ensure 'rtype' and 'rfile' match your Q-Chem output.

```python
# dens_ana.in — full example for Q-Chem TDDFT
rtype=qctddft             # program: qcadc|qctddft|fchk|ricc2|escf|rassi|colmrci|
                          #          colmcscf|orca|cclib|adf|tddftb|dftmrci|onetep|nos
rfile=qchem.out           # main QC output file
mo_file=qchem.mld         # MO coefficients in Molden format
coor_file=qchem.out       # coordinate source file
coor_format=qcout         # format: qcout|xyz|tmol|col|...
read_libwfa=False         # parse libwfa section instead of full TDMs
TDA=False                 # use TDA results (qctddft only)

# Fragment definition (atom indices, 1-based)
at_lists=[[1,2,3,4,5,6],[7,8,9,10,11,12]]

# Omega matrix formula: 0=simple Mulliken, 1=Mulliken, 2=Löwdin
Om_formula=2

# List of properties to compute and print
prop_list=['Om', 'POS', 'PR', 'CT', 'COH', 'CTnt', 'PRNTO', 'Z_HE', 'RMSeh']

# Electron/hole populations: 0=none, 1=fragments, 2=fragments+atoms, 3=basis
eh_pop=1

# NTO analysis
comp_ntos=True            # compute NTOs via SVD
comp_dntos=False          # compute domain NTOs / conditional densities
jmol_orbitals=True        # write Jmol scripts for NTOs
molden_orbitals=False     # write Molden files for NTOs
alphabeta=False           # use alpha/beta spin labels for hole/particle
cube_orbitals=False       # write cube files (requires orbkit)
min_occ=0.05              # minimum occupation to include in orbital output

# Density cube files (require orbkit)
comp_p_h_dens=False       # particle/hole densities
comp_rho0n=False          # ground-to-excited transition densities
numproc=1                 # CPUs for orbkit
orbkit_extend=4.0         # cube extension beyond molecule (Å)
orbkit_step=0.4           # cube grid step size (Å)

# VMD network files (require cube files)
vmd_ntos=False
vmd_ph_dens=False
vmd_rho0n=False
vmd_ntos_iv=0.01          # NTO isosurface value for VMD

# Output control
output_file=tden_summ.txt
print_OmFrag=True         # write OmFrag.txt
print_sorted=True         # sort output by excitation energy
lvprt=1                   # print level (0=minimal, 1=normal, 2=verbose)
output_prec=(7,3)         # table precision: (total digits, decimal places)
```

--------------------------------

### Setup TheoDORE Environment Variables

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/installation.rst

Bash script to set the THEODIR, PATH, and PYTHONPATH environment variables for TheoDORE. Add these lines to your .bashrc or source the script directly.

```bash
#!/bin/bash
export THEODIR=/yourpath/TheoDORE/TheoDORE_v.s
export PATH=$THEODIR/bin:$PATH
export PYTHONPATH=$THEODIR:$PYTHONPATH
```

--------------------------------

### TheoDORE Property List for NTO Analysis

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/transition_density_analysis.rst

This example specifies the property list for Natural Transition Orbital (NTO) analysis in TheoDORE. 'PRNTO' is the NTO participation ratio, and 'S_HE', 'Z_HE' are entanglement measures.

```python
prop_list=['PRNTO', 'S_HE', 'Z_HE']
```

--------------------------------

### Install Packages with Conda

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/installation.rst

Commands to install necessary scientific packages using the Anaconda package manager.

```bash
conda install numpy matplotlib
```

```bash
conda install -c openbabel openbabel
```

--------------------------------

### Columbus MCSCF input for transition moments

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Example of an 'mcdenin' file structure for Columbus MCSCF calculations to compute transition moments between states. The file specifies the states and DRT.

```input
MCSCF
1  2  1  1
1  3  1  1
1  4  1  1
1  5  1  1
1  6  1  1
```

--------------------------------

### Gaussian TDDFT Input Configuration

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Example Gaussian input for TDDFT analysis, including options for full population analysis and CI vector printing.

```text
#p PBEPBE/6-31G* td=(singlets, nstates=10) pop=full iop(9/40=3) GFINPUT
```

--------------------------------

### TheoDORE Property List for Charge Transfer

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/transition_density_analysis.rst

This example shows how to specify a list of properties for charge transfer analysis in TheoDORE. 'Om' refers to the charge transfer number, and other properties like 'POS', 'PR', 'CT', 'CTnt' provide additional descriptors.

```python
prop_list=['Om', 'POS', 'PR', 'CT', 'CTnt']
```

--------------------------------

### Gaussian NMR Calculation Input

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/chemical_shielding.rst

Example Gaussian input file for an NMR calculation, with shielding tensors indicated as dummy (Bq) atoms.

```gaussian
# PBE1PBE/Def2SVP scf=tight nmr

Shielding tensors

0 1
C          0.00000        1.20802        0.69749
C          0.00000        1.20802       -0.69749
C          0.00000       -0.00000       -1.39501
C         -0.00000       -1.20802       -0.69749
C         -0.00000       -1.20802        0.69749
C         -0.00000       -0.00000        1.39501
H          0.00000        2.15464       -1.24395
H         -0.00000        2.15464        1.24395
H         -0.00000       -2.15464       -1.24395
H          0.00000       -0.00000       -2.48803
H         -0.00000       -0.00000        2.48803
H         -0.00000       -2.15464        1.24395
Bq         0.0            0.0            0.0
Bq         1.0            0.0            0.0
Bq         2.0            0.0            0.0
```

--------------------------------

### Run TheoDORE CLI with Options and Header

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/usage.rst

This snippet demonstrates running the TheoDORE CLI with specified subparsers and enabling the header. It customizes the order of main elements and formatting for arguments and subparsers.

```bash
theodore run
   :subparsers: options(*)
   :header: True

    main_order = comment, usage, args, space
    alias = theodore

    [arg_format]
    name = 20
    comment = 60

    [subparser_format]
    name = 25
    comment = 60
```

--------------------------------

### Display TheoDORE Help Options

Source: https://github.com/felixplasser/theodore-qc/blob/main/README.rst

Display a list of all implemented options for the TheoDORE driver script by running 'theodore -h'.

```bash
theodore -h
```

--------------------------------

### Configure Q-Chem for Molden output

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Set these options in the Q-Chem input file to output orbitals in Molden format to the standard output file. This requires extracting the Molden file and renaming it to 'qchem.mld'.

```input
read_libwfa=False
cis_ampl_print	1
print_orbitals	5000
molden_format	true
```

--------------------------------

### Check Logfile Compatibility with cc_check.py

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Use this script to quickly verify if a logfile can be parsed by the cclib library. Ensure you have cclib installed.

```bash
cc_check.py <logfile>
```

--------------------------------

### Load VIST Visualization State in VMD

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/chemical_shielding.rst

Command to launch VMD and load a VIST visualization state file.

```bash
vmd -e VIST.vmd
```

--------------------------------

### Generate Input File with `theodore theoinp`

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

Interactively creates the `dens_ana.in` file by prompting for calculation details. Can also generate only fragment definitions from a coordinate file.

```bash
# Full interactive input generation → writes dens_ana.in
theodore theoinp

# Only generate fragment (at_lists) definition from an xyz file
theodore theoinp -a geom.xyz
```

```text
# Example resulting dens_ana.in for a Q-Chem TDDFT job with 2 fragments:
# rtype=qctddft
# rfile=qchem.out
# mo_file=qchem.mld
# coor_file=qchem.out
# coor_format=qcout
# at_lists=[[1,2,3,4,5,6],[7,8,9,10,11,12]]
# Om_formula=2
# prop_list=['Om', 'POS', 'PR', 'CT', 'COH', 'CTnt', 'PRNTO', 'Z_HE', 'RMSeh']
# comp_ntos=True
# comp_dntos=False
# eh_pop=1
# jmol_orbitals=True
# molden_orbitals=False
```

--------------------------------

### VIST Plotting Command Line Help

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/chemical_shielding.rst

Displays help for the theodore plot_vist command, outlining available options for VIST analysis.

```text
plot_VIST.py [options] <logfile1> <logfile2>
Command line options:
 -h, -H, --help: print this help
 -v, --vist    : VIST for only these dummy atoms, e.g. -v '0 3 5'
 -o            : Name of output file (for VMD)
 -s, --scale   : Scale factor VIST dumb-bells
 -c, --coor    : Create coordinate files (using cclib)
 -p            : Render and plot all tensors separately
 -l/--lab_min  : Add labels for eigenvalues above this value (in ppm), e.g. -l 10
 -q/--qccode   : Quantum chemistry code (g09, qchem, turbomole)
```

--------------------------------

### Manual Molecular Fragment Definition

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/input_generation.rst

Example of manually defining molecular fragments for TheoDORE analysis. This input specifies two fragments, with the first containing atoms 1, 3, and 4, and the second containing atoms 2, 5, and 6.

```python
at_lists = [ [1,3,4], [2,5,6] ]
```

--------------------------------

### Transition Density Analysis with tden_ana

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

Use lib_tden.tden_ana to read MO coefficients, parse transition densities, compute descriptors like Omega matrices and NTOs, and generate output files. Requires input options and potentially MO coefficients.

```python
from theodore import input_options, lib_tden, lib_exciton

# Load options from dens_ana.in
ioptions = input_options.tden_ana_options('dens_ana.in')

# Initialize analysis object
tdena = lib_tden.tden_ana(ioptions)

# Read MO coefficients (Molden format, if mo_file is set)
if 'mo_file' in ioptions:
    tdena.read_mos()

# Parse transition density matrices from QC output
tdena.read_dens()

# Compute atom-resolved Omega matrix (required for OmFrag and eh_pop)
if 'at_lists' in ioptions or ioptions['eh_pop'] >= 1:
    tdena.compute_all_OmAt()

# Compute fragment-level Omega matrix and write OmFrag.txt
if 'at_lists' in ioptions:
    tdena.compute_all_OmFrag()
    tdena.fprint_OmFrag()           # → OmFrag.txt

# NTO decomposition via SVD
if ioptions['comp_ntos']:
    tdena.compute_all_NTO()         # → nto_jmol.spt, nto.html (if jmol_orbitals=True)

# Domain NTOs and conditional densities
if ioptions['comp_dntos']:
    tdena.compute_all_DNTO()

# Particle/hole densities as cube files (requires orbkit)
if ioptions['comp_p_h_dens']:
    tdena.compute_p_h_dens()

# Transition densities as cube files (requires orbkit)
if ioptions['comp_rho0n']:
    tdena.compute_rho_0_n()

# Exciton analysis: RMSeh, MAeh, Eb
exca = lib_exciton.exciton_analysis()
exca.get_distance_matrix(tdena.struc)   # builds interatomic distance matrix
tdena.analyze_excitons(exca)            # adds RMSeh, MAeh, Eb to state_list

# Print electron/hole populations per fragment
tdena.print_all_eh_pop()                # → ehFrag.txt

# Print final summary table → tden_summ.txt
tdena.print_summary()

# Access individual state results programmatically
for state in tdena.state_list:
    print(state['name'], state['exc_en'],
          state.get('Om'), state.get('CT'), state.get('RMSeh'))
```

--------------------------------

### theoinp command-line options

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/input_generation.rst

Configuration for the 'theodore run' command with 'theoinp' subparsers. This defines formatting for argument and subparser displays.

```ini
alias = theodore

[arg_format]
name = 25
comment = 60

[subparser_format]
name = 25
comment = 60
```

--------------------------------

### Run Q-Chem Specific Tests

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/installation.rst

Commands to navigate to the Q-CHEM directory, run Q-Chem related tests, and then execute the general TheoDORE tests for the Q-CHEM module.

```bash
cd QCHEM
./run_qchem.bash [cs]*
cd ..
pytest-3 QCHEM
```

--------------------------------

### Analyze Transition Density Matrices with TheoDORE

Source: https://github.com/felixplasser/theodore-qc/blob/main/README.rst

Analyze transition density matrices using the 'theodore analyze_tden' command.

```bash
theodore analyze_tden
```

--------------------------------

### Parse Q-Chem TDDFT output summary

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Run this command to obtain a summary of the Q-Chem/libwfa TDDFT job.

```bash
theodore parse_libwfa qchem.out [qctddft / qctda]
```

--------------------------------

### State Density Analysis with sden_ana

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

Utilize lib_sden.sden_ana for state density analysis, including natural orbitals, attachment/detachment densities, bond orders, and population analysis. Reads MO coefficients and density information.

```python
from theodore import input_options, lib_sden

ioptions = input_options.sden_ana_options('dens_ana.in')

sdena = lib_sden.sden_ana(ioptions)
if 'mo_file' in ioptions:
    sdena.read_mos()
sdena.read_dens()

# Natural orbital analysis (occupations, orbital characters)
if ioptions['NO_ana']:
    sdena.compute_all_NO()

# Attachment/detachment densities → natural difference orbitals (NDOs)
# Adds 'p' (number of electrons promoted) to each state
if ioptions['AD_ana']:
    sdena.compute_all_AD()         # → ndo_jmol.spt, ndo.html

# Mayer bond orders and valence indices
if ioptions['BO_ana']:
    sdena.compute_all_BO()
    sdena.print_all_BO()           # prints bond order tables

# Compute density cube files (requires orbkit)
if ioptions['comp_rho']:
    sdena.compute_rho()

# Mulliken/Löwdin population tables
if ioptions['pop_ana']:
    sdena.print_all_pop_table()

# Summary table → sden_summ.txt
sdena.print_summary()

# Access state results
for state in sdena.state_list:
    print(state['name'], state.get('nu'), state.get('nunl'), state.get('p'))
```

--------------------------------

### Run State Density Analysis

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

Analyzes state density matrices to compute natural orbitals, attachment/detachment analysis, bond orders, and populations. Requires a `dens_ana.in` input file.

```bash
theodore analyze_sden
```

```bash
theodore analyze_sden -k
```

```bash
# --- Example dens_ana.in for Columbus MR-CI state density analysis ---
# rtype=nos
# mo_file=MOLDEN/molden_mo_mc.sp
# coor_file=geom
# coor_format=col
# ana_files=['MOLDEN/molden_no_mc.sp.1','MOLDEN/molden_no_mc.sp.2','MOLDEN/molden_no_mc.sp.3']
# prop_list=['nu', 'nunl', 'p']
# NO_ana=True
# AD_ana=True
# BO_ana=True
# pop_ana=True
# jmol_orbitals=True
# molden_orbitals=False
```

--------------------------------

### Generate TheoDORE Input

Source: https://github.com/felixplasser/theodore-qc/blob/main/README.rst

Generate input files for TheoDORE using the 'theodore theoinp' command.

```bash
theodore theoinp
```

--------------------------------

### Python API — tden_ana (Transition Density Analysis)

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

The lib_tden.tden_ana class provides a full programmatic interface for transition density matrix analysis, including reading MO coefficients, parsing transition densities, computing descriptors, and writing output files.

```APIDOC
## Python API — `tden_ana` (Transition Density Analysis)

The `lib_tden.tden_ana` class provides the full programmatic interface for transition density matrix analysis. It reads MO coefficients, parses transition densities, computes all descriptors, and writes output files.

```python
from theodore import input_options, lib_tden, lib_exciton

# Load options from dens_ana.in
ioptions = input_options.tden_ana_options('dens_ana.in')

# Initialize analysis object
tdena = lib_tden.tden_ana(ioptions)

# Read MO coefficients (Molden format, if mo_file is set)
if 'mo_file' in ioptions:
    tdena.read_mos()

# Parse transition density matrices from QC output
tdena.read_dens()

# Compute atom-resolved Omega matrix (required for OmFrag and eh_pop)
if 'at_lists' in ioptions or ioptions['eh_pop'] >= 1:
    tdena.compute_all_OmAt()

# Compute fragment-level Omega matrix and write OmFrag.txt
if 'at_lists' in ioptions:
    tdena.compute_all_OmFrag()
    tdena.fprint_OmFrag()           # → OmFrag.txt

# NTO decomposition via SVD
if ioptions['comp_ntos']:
    tdena.compute_all_NTO()         # → nto_jmol.spt, nto.html (if jmol_orbitals=True)

# Domain NTOs and conditional densities
if ioptions['comp_dntos']:
    tdena.compute_all_DNTO()

# Particle/hole densities as cube files (requires orbkit)
if ioptions['comp_p_h_dens']:
    tdena.compute_p_h_dens()

# Transition densities as cube files (requires orbkit)
if ioptions['comp_rho0n']:
    tdena.compute_rho_0_n()

# Exciton analysis: RMSeh, MAeh, Eb
exca = lib_exciton.exciton_analysis()
exca.get_distance_matrix(tdena.struc)   # builds interatomic distance matrix
tdena.analyze_excitons(exca)            # adds RMSeh, MAeh, Eb to state_list

# Print electron/hole populations per fragment
tdena.print_all_eh_pop()                # → ehFrag.txt

# Print final summary table → tden_summ.txt
tdena.print_summary()

# Access individual state results programmatically
for state in tdena.state_list:
    print(state['name'], state['exc_en'],
          state.get('Om'), state.get('CT'), state.get('RMSeh'))
```
```

--------------------------------

### Enable libwfa analysis in Q-Chem ADC

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Set these options in the Q-Chem input file to enable libwfa analysis for ADC calculations. Ensure 'ctnum_mulliken.om' is copied for TheoDORE.

```input
state_analysis    true
adc_print    3
```

--------------------------------

### Run TheoDORE Command-Line Interface

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/usage.rst

This snippet shows the basic command to run the TheoDORE CLI with default argument and subparser formatting. It sets the main order for arguments and aliases the command.

```bash
theodore run

main_order = usage, args, space
alias = theodore

[arg_format]
name = 20
comment = 60

[subparser_format]
name = 25
comment = 60
```

--------------------------------

### Parse Q-Chem libwfa output for ADC

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Run this command to parse the Q-Chem output file for libwfa analysis specific to ADC.

```bash
theodore parse_libwfa qchem.out qcadc
```

--------------------------------

### Analyze Q-Chem TDDFT with TheoDORE

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Run this command to analyze the Q-Chem TDDFT output using TheoDORE, specifying the 'qcttdft' option and that 'state_analysis=True' was used.

```bash
theodore theoinp --qcttdft --state_analysis=True
```

--------------------------------

### Unrestricted Transition Density Analysis with `theodore analyze_tden_unr`

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

Analyzes alpha and beta spins separately for unrestricted calculations, combining results. Output is organized into ALPHA/ and BETA/ subdirectories.

```bash
# dens_ana.in must specify an unrestricted calculation
# rtype=qctddft
# rfile=qchem.out
# mo_file=qchem.mld
# at_lists=[[1,2,3],[4,5,6]]
# prop_list=['Om', 'CT', 'PR', 'S_HE', 'Z_HE']

theodore analyze_tden_unr
```

```text
# Output structure:
#   ALPHA/tden_summ.txt   - alpha-spin results
#   BETA/tden_summ.txt    - beta-spin results
#   (spin-summed table printed to stdout)
```

--------------------------------

### Enable libwfa analysis in Q-Chem TDDFT

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Set these options in the Q-Chem input file to enable libwfa analysis for TDDFT calculations. Ensure 'ctnum_mulliken.om' is copied for TheoDORE.

```input
state_analysis    true
```

--------------------------------

### State-to-State Transition Density Analysis with `theodore analyze_tden_es2es`

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

Computes transition density matrices between excited states, using a specified reference state. The reference state index is set with the -r flag.

```bash
# Use state 2 as the reference (iref=2 means the 2nd excited state)
theodore analyze_tden_es2es -r 2

# With custom input file
theodore analyze_tden_es2es -f dens_ana.in -r 1
```

--------------------------------

### Python API — sden_ana (State Density Analysis)

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

The lib_sden.sden_ana class handles state density matrix analysis, including natural orbitals, attachment/detachment densities, bond orders, and populations.

```APIDOC
## Python API — `sden_ana` (State Density Analysis)

The `lib_sden.sden_ana` class handles state density matrix analysis including natural orbitals, attachment/detachment, bond orders, and populations.

```python
from theodore import input_options, lib_sden

ioptions = input_options.sden_ana_options('dens_ana.in')

sdena = lib_sden.sden_ana(ioptions)
if 'mo_file' in ioptions:
    sdena.read_mos()
sdena.read_dens()

# Natural orbital analysis (occupations, orbital characters)
if ioptions['NO_ana']:
    sdena.compute_all_NO()

# Attachment/detachment densities → natural difference orbitals (NDOs)
# Adds 'p' (number of electrons promoted) to each state
if ioptions['AD_ana']:
    sdena.compute_all_AD()         # → ndo_jmol.spt, ndo.html

# Mayer bond orders and valence indices
if ioptions['BO_ana']:
    sdena.compute_all_BO()
    sdena.print_all_BO()           # prints bond order tables

# Compute density cube files (requires orbkit)
if ioptions['comp_rho']:
    sdena.compute_rho()

# Mulliken/Löwdin population tables
if ioptions['pop_ana']:
    sdena.print_all_pop_table()

# Summary table → sden_summ.txt
sdena.print_summary()

# Access state results
for state in sdena.state_list:
    print(state['name'], state.get('nu'), state.get('nunl'), state.get('p'))
```
```

--------------------------------

### ORCA TDDFT Input Configuration

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Configure dens_ana.in for ORCA TDDFT analysis using a Molden file and cclib.

```text
rtype='orca'
rfile='orca.out'
read_binary=True
mo_file='orca.molden.input'
```

--------------------------------

### Molcas &WFA Module Input

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Use the &WFA module in Molcas to enable libwfa analysis. Ensure the h5file points to the rassi.h5 file.

```text
&RASSI
TRD1

&WFA
h5file = $Project.rassi.h5
```

--------------------------------

### Analyze Natural Orbital Files Directly

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

Directly analyzes natural orbital files in Molden format without a full `dens_ana.in`. Useful for quick analysis of pre-existing NO files. The first file is used for the AO overlap matrix.

```bash
theodore analyze_nos state0.mld state1.mld state2.mld
```

```bash
theodore analyze_nos s0.mld s1.mld s2.mld -r ref_mos.mld -o 2.0
```

```bash
theodore analyze_nos alpha.mld -u
```

```bash
theodore analyze_nos nos.mld -e
```

--------------------------------

### Enable fchk file parsing in Q-Chem

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Set these options in the Q-Chem input file to enable parsing of formatted checkpoint (fchk) files for transition density matrices. This is recommended for testing purposes.

```input
state_analysis    true
gui               2
```

--------------------------------

### Molcas MS-CASPT2 Input

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Configure MS-CASPT2 calculations in Molcas for TheoDORE analysis. Note that EJOB keyword is not compatible, leading to inconsistent energies and oscillator strengths.

```text
&CASPT2
multistate = 4 1 2 3 4
imag = 0.3

>> SAVE $Project.JobMix JOB001

&RASSI
NROFJOBIPHS
1 4
1 2 3 4
CIPR
TRD1
```

--------------------------------

### Generate VMD Visualization Network Scripts

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

Creates VMD script files and an HTML gallery for batch visualization of cube files (NTOs, densities). Supports normal and DNTO modes.

```bash
theodore vmd_plots nto_S1_1o.cb nto_S1_1v.cb nto_S2_1o.cb nto_S2_1v.cb
```

```bash
theodore vmd_plots rho_p_S1_hole.cb rho_p_S1_elec.cb
```

--------------------------------

### Run VIST Plotting Script

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/chemical_shielding.rst

Executes the plot_VIST.py script to generate VIST visualizations from a Gaussian log file.

```bash
plot_VIST.py gaussian.log
```

--------------------------------

### Copy Transition Densities

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Copy the generated transition densities (TRD2*) to a directory named TRD.

```bash
mkdir TRD && cp $WorkDir/TRD2* TRD
```

--------------------------------

### Python API — exciton_analysis

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

The lib_exciton.exciton_analysis class computes approximate exciton descriptors from the atom-resolved Omega matrix and an interatomic distance matrix.

```APIDOC
## Python API — `exciton_analysis`

The `lib_exciton.exciton_analysis` class computes approximate exciton descriptors from the atom-resolved Omega matrix and an interatomic distance matrix.

```python
from theodore import lib_exciton
import numpy

# Initialize and build distance matrix from a structure object (lib_struc.structure)
exca = lib_exciton.exciton_analysis()
exca.get_distance_matrix(struc, U=8.0, eps=2)
# struc: theodore.lib_struc.structure with atomic coordinates loaded
# U: Hubbard parameter for Ohno ERI formula (default 8.0 eV)
# eps: dielectric constant (default 2)

# Given Om (scalar) and OmAt (natom x natom numpy array):
Om   = 0.95
OmAt = numpy.array([[0.05, 0.40], [0.30, 0.20]])  # 2-atom example

rms_eh = exca.ret_RMSeh(Om, OmAt)   # RMS electron-hole separation (Å)
ma_eh  = exca.ret_MAeh(Om, OmAt)    # Mean absolute e-h distance (Å)
Eb     = exca.ret_Eb(Om, OmAt)      # Approximate exciton binding energy (eV)

print(f"RMSeh = {rms_eh:.3f} Å")
print(f"MAeh  = {ma_eh:.3f} Å")
print(f"Eb    = {Eb:.3f} eV")
# Example output:
# RMSeh = 3.142 Å
# MAeh  = 2.871 Å
# Eb    = 1.204 eV
```
```

--------------------------------

### Turbomole MO File Generation

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Generate MO files for Turbomole calculations, ensuring frozen orbitals are included by modifying the control file and running tm2molden.

```bash
#!/bin/bash
sed -i "/implicit core/d" control
echo -e "\n\n"|tm2molden
```

--------------------------------

### Visualize densities using TheoDORE and VMD

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/orbitals_and_densities.rst

Generate cube files for densities and visualize them using VMD. This command processes all cube files in the current directory.

```bash
theodore vmd_plots *.cb
```

--------------------------------

### Specifying Conditional Density Cube File Generation

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/transition_density_analysis.rst

This prompt in TheoDORE allows users to specify whether to compute conditional densities as cube files and for which type of density (hole, electron, or both).

```text
Compute conditional densities as cube files?
 0 - no, 1 - hole, 2 - electron, 3 - both (comp_dnto_dens):
Choice: [0] 1
```

--------------------------------

### Enabling Conditional Densities and Domain NTOs

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/transition_density_analysis.rst

This interactive prompt in TheoDORE allows users to enable the computation of conditional densities and domain NTOs. Setting the choice to 'y' activates this analysis.

```text
Perform analysis of domain NTOs and conditional densities? (comp_dntos):
Choice (y/n): [n] y
```

--------------------------------

### Analyze Transition Density Matrix with `theodore analyze_tden`

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

Performs excited-state analysis, computing charge-transfer descriptors and NTOs. Accepts a custom input file via the -f flag and lists keywords with -k.

```bash
# Run with default input file dens_ana.in
theodore analyze_tden

# Specify a different input file
theodore analyze_tden -f my_input.in

# Print all available keywords and their defaults
theodore analyze_tden -k
```

```text
# --- Example dens_ana.in for Turbomole ricc2 with 3 fragments ---
# rtype=ricc2
# rfile=ricc2.out
# mo_file=molden.input
# coor_file=coord
# coor_format=tmol
# at_lists=[[1,2,3],[4,5,6],[7,8,9]]
# Om_formula=2
# prop_list=['Om', 'POS', 'PR', 'CT', 'COH', 'CTnt', 'PRNTO', 'Z_HE', 'RMSeh']
# comp_ntos=True
# jmol_orbitals=True
# eh_pop=1
# print_OmFrag=True

# Outputs produced:
#   tden_summ.txt      - summary table with all descriptors per state
#   OmFrag.txt         - raw Omega matrices for all states
#   ehFrag.txt         - electron/hole populations per fragment
#   nto_jmol.spt       - Jmol script to visualize NTOs
#   nto.html           - HTML NTO gallery
```

--------------------------------

### Generate Jmol visualization files for orbitals

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/orbitals_and_densities.rst

Use the 'jmol_mos' tool to generate Molden files suitable for Jmol visualization. This command can accept wildcard patterns for input files.

```bash
theodore jmol_mos nto*.mld
```

--------------------------------

### ORCA TDDFT Molden File Generation

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Generate a Molden file from ORCA output using 'orca_2mkl orca -molden'.

```bash
orca_2mkl orca -molden
```

--------------------------------

### Parse libwfa Analysis Output with theodore parse_libwfa

Source: https://context7.com/felixplasser/theodore-qc/llms.txt

This command parses Q-Chem's libwfa output to extract exciton descriptors like exciton size, electron-hole distance, and correlation. It requires 'rtype=qcadc' or 'read_libwfa=True' in 'dens_ana.in'.

```bash
# dens_ana.in requires:
#   rtype=qcadc  (or libwfa / qctddft with read_libwfa=True)
#   read_libwfa=True
#   rfile=qchem.out

theodore analyze_tden -f dens_ana.in

# Alternatively, use parse_libwfa to extract the table standalone:
theodore parse_libwfa
# Outputs tden_summ.txt with libwfa descriptors:
#   dexc  - exciton size (Å)
#   dH-E  - electron-hole distance (Å)
#   sigH  - hole size (Å)
#   sigE  - electron size (Å)
#   COV   - covariance
#   Corr  - correlation coefficient
#   sigD  - donor size (DDM)
#   sigA  - acceptor size (DDM)
```

--------------------------------

### Theodore Command Line for TD Analysis

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/transition_density_analysis.rst

This command initiates the transition density matrix analysis. It specifies the subcommand 'analyze_tden' and configures output formatting.

```bash
theodore run -subparsers options(analyze_tden)
   main_order = usage, pos_args, opt_args, subparser_args, space
   alias = theodore

   [arg_format]
   name = 20
   comment = 60
```

--------------------------------

### Interactive Fragment Decomposition Plotting (Populations)

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/plotting.rst

Use the interactive script `plot_frag_decomp` after `analyze_tden` to visualize the fragment decomposition of electron and hole populations in excited states.

```bash
plot_frag_decomp
```

--------------------------------

### DFTB+ Input Files

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

List of files required by the DFTB+ interface in TheoDORE for TDDFTB analysis.

```text
EXC.DAT (main excited state information) - specified as 'rfile'
eigenvec.out (MO coefficients) - specified as 'mo_file'
XplusY.DAT (response vector)
SPX.DAT (ordering of response vector)
geom.xyz (geometry information)
detailed.out (orbital occupations and energies)
wfc.3ob-3-1.hsd (DFTB parameter file)
```

--------------------------------

### Process Multiple VIST Outputs

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/chemical_shielding.rst

Command to process multiple Gaussian log files from subdirectories, extracting specific shielding tensors and coordinates.

```bash
theodore plot_vist -c -v '0 4' */gaussian.log
```

--------------------------------

### ORCA Output Options for cclib

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/program_specific_information.rst

Set ORCA output options to enable full parsing with the cclib library.

```text
%output
 PrintLevel Normal
 Print[ P_MOs ] 1
 Print[ P_Overlap ] 1
end
```

--------------------------------

### Generate Absorption Spectrum

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/plotting.rst

Create a convoluted absorption spectrum from energies and oscillator strengths parsed by `analyze_tden`. This command can also compute the density of states and apply state restrictions.

```bash
theodore spectrum <tden_summ1> [<tden_summ2> ...]
```

--------------------------------

### Extract Source File

Source: https://github.com/felixplasser/theodore-qc/blob/main/doc/source/installation.rst

Command to extract the TheoDORE source archive.

```bash
tar -xf TheoDORE_v.s.tgz
```