Welcome to pysisyphus documentation!

pysisyphus is a software-suite for the exploration of potential energy surfaces in ground- and excited states. It implements several methods to search for stationary points (minima and first order saddle points) and the calculation of minimum energy paths by means of IRC and Chain of States methods like Nudged Elastic Band and Growing String. Furthermore it provides tools to easily analyze & modify geometries (aligning, translating, interpolating, ...) and to visualize the calculation results/progress.

The required energies, gradients and hessians are calculated by calling external quantum chemistry codes. pysisyphus can also be used as a library to implement custom quantum chemistry workflows.

If any issues arise please open an issue and I'll see if it can be fixed and my time permits it. Contrubtions are welcome, so feel free to submit a PR.

This software is still work in progress. Use at your own risk. Also take a look at the license

Contents:

• 1. Overview of pysisyphus
  • 1.1. Entry points
    • 1.1.1. pysis
    • 1.1.2. pysisplot
    • 1.1.3. pysistrj
  • 1.2. Available calculators
    • 1.2.1. Excited state capabilities
    • 1.2.2. Ground states capabilities
    • 1.2.3. Pure python calculators & Wrappers
  • 1.3. Available algorithms
    • 1.3.1. Chain Of States Methods
    • 1.3.2. Chain Of States Optimizer
    • 1.3.3. Transition state optimization
    • 1.3.4. Intrinsic Reaction Coordinate integrators
  • 1.4. Additional remarks
• 2. Installation
  • 2.1. Preparing an environment
  • 2.2. Installation from PyPI with pip
  • 2.3. Installation from source
  • 2.4. Setting up .pysisyphusrc
  • 2.5. Example runpsi4.sh
  • 2.6. Example runmopac.sh
  • 2.7. Example runcfour.sh
  • 2.8. Verifying Installation
• 3. Installation via Nix
  • 3.1. Prerequisites
  • 3.2. Caching
  • 3.3. Usage
• 4. Worked Example
• 5. Coordinate Systems
  • 5.1. Supported Coordinate Systems
    • 5.1.1. Cartesian Coordinates
    • 5.1.2. Redundant Internal Coordinates
    • 5.1.3. Delocalized Internal Coordinates (DLC)
    • 5.1.4. Translation & Rotation Internal Coordinates (TRIC)
  • 5.2. Supported File Formats
    • 5.2.1. Z-Matrix example
  • 5.3. YAML Input
    • 5.3.1. Inline input
    • 5.3.2. Types of Primitive Coordinates
    • 5.3.3. Define Additional Primitives
    • 5.3.4. Freeze Atoms
    • 5.3.5. Constraints
    • 5.3.6. Isotopes
  • 5.4. Geometry & RedundantCoords
    • Geometry
      • Geometry.__init__()
      • Geometry.align_principal_axes()
      • Geometry.all_energies
      • Geometry.approximate_radius()
      • Geometry.as_ascii_art()
      • Geometry.as_ase_atoms()
      • Geometry.as_g98_list()
      • Geometry.as_xyz()
      • Geometry.assert_cart_coords()
      • Geometry.assert_compatibility()
      • Geometry.atom_indices()
      • Geometry.atom_types
      • Geometry.atom_xyz_iter()
      • Geometry.atomic_numbers
      • Geometry.bond_sets
      • Geometry.calc_double_ao_overlap()
      • Geometry.calc_energy()
      • Geometry.calc_energy_and_forces()
      • Geometry.calc_relaxed_density()
      • Geometry.calc_wavefunction()
      • Geometry.cart_coords
      • Geometry.cart_forces
      • Geometry.cart_gradient
      • Geometry.cart_hessian
      • Geometry.center()
      • Geometry.center_of_mass
      • Geometry.center_of_mass_at()
      • Geometry.centroid
      • Geometry.clear()
      • Geometry.comment
      • Geometry.coord_types
      • Geometry.coords
      • Geometry.coords3d
      • Geometry.coords_by_type
      • Geometry.copy()
      • Geometry.copy_all()
      • Geometry.covalent_radii
      • Geometry.del_atoms()
      • Geometry.describe()
      • Geometry.dump_trj()
      • Geometry.dump_xyz()
      • Geometry.eckart_projection()
      • Geometry.energy
      • Geometry.fd_coords3d_gen()
      • Geometry.forces
      • Geometry.get_energy_and_cart_forces_at()
      • Geometry.get_energy_and_cart_hessian_at()
      • Geometry.get_energy_and_forces_at()
      • Geometry.get_energy_at()
      • Geometry.get_energy_at_cart_coords()
      • Geometry.get_fragments()
      • Geometry.get_hessian_projector()
      • Geometry.get_imag_frequencies()
      • Geometry.get_normal_modes()
      • Geometry.get_restart_info()
      • Geometry.get_root_energy()
      • Geometry.get_sphere_radius()
      • Geometry.get_subgeom()
      • Geometry.get_subgeom_without()
      • Geometry.get_temporary_coords()
      • Geometry.get_thermoanalysis()
      • Geometry.get_trans_rot_projector()
      • Geometry.gradient
      • Geometry.has_all_energies()
      • Geometry.has_energy
      • Geometry.has_forces
      • Geometry.has_hessian()
      • Geometry.hessian
      • Geometry.inertia_tensor
      • Geometry.is_analytical_2d
      • Geometry.is_linear
      • Geometry.jmol()
      • Geometry.layers
      • Geometry.mass_weigh_hessian()
      • Geometry.masses
      • Geometry.masses_rep
      • Geometry.mm_inv
      • Geometry.mm_sqrt_inv
      • Geometry.modes3d()
      • Geometry.moving_atoms
      • Geometry.moving_atoms_jmol()
      • Geometry.mw_coords
      • Geometry.mw_gradient
      • Geometry.mw_hessian
      • Geometry.principal_axes_are_aligned()
      • Geometry.reparametrize()
      • Geometry.reset_coords()
      • Geometry.rmsd()
      • Geometry.rotate()
      • Geometry.set_calculator()
      • Geometry.set_coord()
      • Geometry.set_coords()
      • Geometry.set_h5_hessian()
      • Geometry.set_restart_info()
      • Geometry.set_results()
      • Geometry.standard_orientation()
      • Geometry.sum_formula
      • Geometry.td_1tdms
      • Geometry.tmp_xyz_handle()
      • Geometry.total_mass
      • Geometry.unweight_mw_hessian()
      • Geometry.vdw_radii
      • Geometry.vdw_volume()
      • Geometry.wavefunction
      • Geometry.without_hydrogens()
      • Geometry.zero_frozen_forces()
    • normalize_atoms()
    • HybridRedundantCoords
    • RedundantCoords
      • RedundantCoords.B
      • RedundantCoords.B_inv
      • RedundantCoords.B_inv_prim
      • RedundantCoords.B_prim
      • RedundantCoords.Bt_inv
      • RedundantCoords.Bt_inv_prim
      • RedundantCoords.C
      • RedundantCoords.P
      • RedundantCoords.backtransform_hessian()
      • RedundantCoords.bend_atom_indices
      • RedundantCoords.bend_indices
      • RedundantCoords.bond_atom_indices
      • RedundantCoords.bond_indices
      • RedundantCoords.bond_typed_prims
      • RedundantCoords.cartesian_indices
      • RedundantCoords.clear()
      • RedundantCoords.constrained_indices
      • RedundantCoords.coords
      • RedundantCoords.coords3d
      • RedundantCoords.dihedral_atom_indices
      • RedundantCoords.dihedral_indices
      • RedundantCoords.eval()
      • RedundantCoords.get_K_matrix()
      • RedundantCoords.get_index_of_typed_prim()
      • RedundantCoords.get_prim_internals_by_indices()
      • RedundantCoords.inv_B()
      • RedundantCoords.inv_Bt()
      • RedundantCoords.linear_bend_indices
      • RedundantCoords.log()
      • RedundantCoords.log_int_grad_msg()
      • RedundantCoords.outofplane_indices
      • RedundantCoords.prim_coords
      • RedundantCoords.prim_indices_set
      • RedundantCoords.prim_internals
      • RedundantCoords.primitives
      • RedundantCoords.print_typed_prims()
      • RedundantCoords.project_hessian()
      • RedundantCoords.project_vector()
      • RedundantCoords.return_inds()
      • RedundantCoords.rotation_indices
      • RedundantCoords.set_inds_from_typed_prims()
      • RedundantCoords.set_primitive_indices()
      • RedundantCoords.transform_forces()
      • RedundantCoords.transform_hessian()
      • RedundantCoords.transform_int_step()
      • RedundantCoords.translation_indices
      • RedundantCoords.typed_prims
    • TMTRIC
    • TRIC
    • get_tr_projector()
  • 5.5. Related Literature
• 6. Calculators
  • 6.1. YAML input
  • 6.2. Calculator base classes
    • Calculator
      • Calculator.__init__()
      • Calculator.apply_keep_kind()
      • Calculator.apply_set_plans()
      • Calculator.build_set_plans()
      • Calculator.clean()
      • Calculator.conf_key
      • Calculator.force_num_hessian()
      • Calculator.geom_from_fn()
      • Calculator.get_cmd()
      • Calculator.get_energy()
      • Calculator.get_forces()
      • Calculator.get_hessian()
      • Calculator.get_num_hessian()
      • Calculator.get_relaxed_density()
      • Calculator.get_restart_info()
      • Calculator.get_stored_wavefunction()
      • Calculator.get_wavefunction()
      • Calculator.keep()
      • Calculator.load_wavefunction_from_file()
      • Calculator.log()
      • Calculator.make_fn()
      • Calculator.name
      • Calculator.popen()
      • Calculator.prepare()
      • Calculator.prepare_coords()
      • Calculator.prepare_input()
      • Calculator.prepare_path()
      • Calculator.prepare_pattern()
      • Calculator.prepare_turbo_coords()
      • Calculator.prepare_xyz_string()
      • Calculator.print_capabilities()
      • Calculator.print_out_fn()
      • Calculator.restore_org_hessian()
      • Calculator.run()
      • Calculator.run_after()
      • Calculator.set_restart_info()
      • Calculator.verify_chkfiles()
    • HessKind
      • HessKind.NUMERICAL
      • HessKind.ORG
    • KeepKind
      • KeepKind.ALL
      • KeepKind.LATEST
      • KeepKind.NONE
    • SetPlan
      • SetPlan.condition()
      • SetPlan.fail
      • SetPlan.key
      • SetPlan.name
  • 6.3. OverlapCalculator base class
  • 6.4. Calculators with Excited state capabilities
    • 6.4.1. Gaussian09
    • 6.4.2. Gaussian16
    • 6.4.3. OpenMolcas
    • 6.4.4. ORCA 4.2.1 / 5.0.1
    • 6.4.5. PySCF 1.7.6
    • 6.4.6. Turbomole 7.x
    • 6.4.7. DFTB+ 20.x
  • 6.5. Calculators with Ground state capabilities
    • 6.5.1. MOPAC 2016
    • 6.5.2. Psi4
    • 6.5.3. QCEngine
    • 6.5.4. XTB 6.x
    • 6.5.5. Dalton
    • 6.5.6. OpenBabel
    • 6.5.7. CFOUR
  • 6.6. Meta (wrapping) Calculators
    • 6.6.1. ExternalPotential
    • 6.6.2. Restraint
    • 6.6.3. HarmonicSphere
    • 6.6.4. LogFermi
    • 6.6.5. RMSD
    • 6.6.6. DFT-D3
    • 6.6.7. AFIR
      • AFIR
      • CovRadiiSumZero
      • afir_closure()
      • get_data_model()
    • 6.6.8. ONIOM
    • 6.6.9. Dimer
  • 6.7. Pure Python calculators
    • 6.7.1. Sympy 2D Potentials
    • 6.7.2. Lennard-Jones
    • 6.7.3. FakeASE
    • 6.7.4. TIP3P
• 7. Minimization
  • 7.1. YAML Example
  • 7.2. Convergence Thresholds
  • 7.3. Available Optimizers
• 8. Minimization with Microiterations
  • 8.1. YAML input
  • 8.2. Example using pysisyphus' ONIOM
  • 8.3. Example with sockets & i-PI-protocol
• 9. Relaxed Scans
• 10. Excited State Optimization
  • 10.1. YAML Example
  • 10.2. Optimization of Conical Intersections
• 11. Chain Of States Methods
  • 11.1. String method
  • 11.2. Nudged Elastic Band
  • 11.3. Parallelization
  • 11.4. General remarks
  • 11.5. YAML example(s)
  • 11.6. General advice for COS optimizations
  • 11.7. Chain Of States base class
  • 11.8. Chain Of State Methods
    • 11.8.1. Nudged Elastic Band (NEB)
    • 11.8.2. Adaptive NEB
    • 11.8.3. Free-End NEB
    • 11.8.4. Simple Zero-Temperature String
  • 11.9. Growing Chain Of States base class
  • 11.10. Growing Chain Of State Methods
    • 11.10.1. Growing String Method
• 12. Transition State Optimization
  • 12.1. Hessian Based TS Optimization
    • 12.1.1. YAML example
  • 12.2. Dimer Method
    • 12.2.1. YAML example
  • 12.3. General advice for TS optimizations
  • 12.4. TSHessianOptimizer base class
  • 12.5. TS-Optimizer using hessian information
    • 12.5.1. Restricted-Step Partitioned-RFO
    • 12.5.2. Restricted-Step Image-Function-RFO
    • 12.5.3. Trust-Region Image-Function Method
  • 12.6. TS-Optimization without hessian information
    • 12.6.1. Dimer method
• 13. Intrinsic Reaction Coordinate (IRC)
  • 13.1. YAML example(s)
  • 13.2. IRC base class
  • 13.3. IRC Integrators
    • 13.3.1. Damped-Velocity-Verlet integrator
    • 13.3.2. Euler integrator
    • 13.3.3. Euler-Predictor-Corrector integrator
    • 13.3.4. Gonzales-Schlegel-2 integrator
    • 13.3.5. Local-Quadratic-Approximation integrator
    • 13.3.6. Modified-Ishida-Morokuma-Komornicki integrator
    • 13.3.7. Runge-Kutta-4 integrator
• 14. Plotting
  • 14.1. Example - Diels-Alder reaction
    • 14.1.1. Plotting optimization progress
    • 14.1.2. Plotting COS optimization progress
    • 14.1.3. Plotting TS-optimization progress
    • 14.1.4. Plotting the Intrinsic Reaction Coordinate
  • 14.2. Example - AFIR
  • 14.3. Example - Excited State Tracking
• 15. Diabatiziation
  • 15.1. General Idea
    • 15.1.1. Rotation Matrix
    • 15.1.2. Cost function
    • 15.1.3. Cost Function Optimization
    • 15.1.4. Densities
  • 15.2. Legacy YAML Interface
  • 15.3. Legacy YAML Interface - Example
  • 15.4. New Interface
  • 15.5. New Interface - Example 1
  • 15.6. New Interface - Example 2
• 16. Identifying the Marcus Dimension
• 17. pysisyphus
  • 17.1. pysisyphus package
    • 17.1.1. Subpackages
      • 17.1.1.1. pysisyphus.benchmarks package
      • 17.1.1.2. pysisyphus.calculators package
      • 17.1.1.3. pysisyphus.cos package
      • 17.1.1.4. pysisyphus.db package
      • 17.1.1.5. pysisyphus.diabatization package
      • 17.1.1.6. pysisyphus.drivers package
      • 17.1.1.7. pysisyphus.dynamics package
      • 17.1.1.8. pysisyphus.franckcondon package
      • 17.1.1.9. pysisyphus.hindered_rotor package
      • 17.1.1.10. pysisyphus.intcoords package
      • 17.1.1.11. pysisyphus.interpolate package
      • 17.1.1.12. pysisyphus.io package
      • 17.1.1.13. pysisyphus.irc package
      • 17.1.1.14. pysisyphus.line_searches package
      • 17.1.1.15. pysisyphus.marcus_dim package
      • 17.1.1.16. pysisyphus.modefollow package
      • 17.1.1.17. pysisyphus.numerov package
      • 17.1.1.18. pysisyphus.numint package
      • 17.1.1.19. pysisyphus.optimizers package
      • 17.1.1.20. pysisyphus.partfuncs package
      • 17.1.1.21. pysisyphus.plotters package
      • 17.1.1.22. pysisyphus.stocastic package
      • 17.1.1.23. pysisyphus.tests package
      • 17.1.1.24. pysisyphus.tsoptimizers package
      • 17.1.1.25. pysisyphus.wavefunction package
      • 17.1.1.26. pysisyphus.wrapper package
    • 17.1.2. Submodules
    • 17.1.3. pysisyphus.Geometry module
      • Geometry
      • normalize_atoms()
    • 17.1.4. pysisyphus.MOCoeffs module
      • MOCoeffs
      • filter_ens()
      • occ_from_occs()
    • 17.1.5. pysisyphus.TablePrinter module
      • TablePrinter
      • center()
      • parse_fstring()
      • res_to_fstring()
    • 17.1.6. pysisyphus.color module
      • bool_color()
      • green()
      • red()
    • 17.1.7. pysisyphus.config module
      • detect_paths()
      • get_cmd()
      • parse_args()
      • run_detect_paths()
    • 17.1.8. pysisyphus.constants module
    • 17.1.9. pysisyphus.elem_data module
      • atomic_numbers_for_atoms()
      • get_tm_indices()
      • masses_for_atoms()
      • nuc_charges_for_atoms()
    • 17.1.10. pysisyphus.exceptions module
      • CalculationFailedException
      • DifferentAtomOrdering
      • HEIIsFirstOrLastException
      • RunAfterCalculationFailedException
    • 17.1.11. pysisyphus.executors module
      • CloudpickleProcessPoolExecutor
      • MaybeScheduler
      • apply_cloudpickle()
    • 17.1.12. pysisyphus.filtertrj module
      • get_unique_internals()
      • parse_args()
      • parse_filter()
      • run()
    • 17.1.13. pysisyphus.finite_diffs module
      • finite_difference_gradient()
      • finite_difference_hessian()
      • finite_difference_hessian_mp()
      • grad_func()
      • periodic_fd_2_8()
      • periodic_finite_difference()
    • 17.1.14. pysisyphus.helpers module
      • FinalHessianResult
      • align_coords()
      • align_geoms()
      • check_for_end_sign()
      • complete_fragments()
      • confirm_input()
      • do_final_hessian()
      • fit_rigid()
      • geom_from_missing_ext()
      • geom_from_xyz_file()
      • geom_loader()
      • geoms_from_trj()
      • get_coords_diffs()
      • get_fragment_xyzs()
      • get_geom_getter()
      • get_tangent_trj_str()
      • imag_modes_from_geom()
      • index_array_from_overlaps()
      • match_geoms()
      • norm_max_rms()
      • np_print()
      • pick_image_inds()
      • print_barrier()
      • procrustes()
      • shake_coords()
      • simple_peaks()
      • slugify_worker()
    • 17.1.15. pysisyphus.helpers_pure module
      • OrderedEnum
      • approx_float()
      • argsort()
      • cache_arrays()
      • check_mem()
      • chunks()
      • describe()
      • eigval_to_wavenumber()
      • estimate()
      • expand()
      • file_or_str()
      • filter_fixture_store()
      • find_closest_sequence()
      • full_expand()
      • get_box()
      • get_clock()
      • get_cubic_crystal()
      • get_input()
      • get_molecular_radius()
      • get_random_path()
      • get_ratio()
      • get_state_label()
      • hash_args()
      • hash_arr()
      • highlight_text()
      • increment_fn()
      • interpolate_colors()
      • json_to_results()
      • kill_dir()
      • log()
      • merge_sets()
      • molecular_volume()
      • recursive_extract()
      • recursive_update()
      • remove_duplicates()
      • render_sp_stats()
      • report_frozen_atoms()
      • report_isotopes()
      • results_to_json()
      • rms()
      • sort_by_central()
      • standard_state_corr()
      • timed()
      • to_sets()
      • to_subscript_num()
      • touch()
    • 17.1.16. pysisyphus.hessian_proj module
      • Orientation
      • get_hessian_projector()
      • get_projector()
      • get_standard_orientation()
      • get_trans_rot_projector()
      • get_trans_rot_vectors()
      • get_unit_orientation()
      • inertia_tensor()
    • 17.1.17. pysisyphus.init_logging module
      • get_fh_logger()
      • init_logging()
      • init_logging_base()
    • 17.1.18. pysisyphus.linalg module
      • are_collinear()
      • cross3()
      • eigvec_grad()
      • fd_rmsd_hessian()
      • get_rot_mat()
      • get_rot_mat_for_coords()
      • gram_schmidt()
      • make_unit_vec()
      • matrix_power()
      • multi_component_sym_mat()
      • norm3()
      • orthogonalize_against()
      • perp_comp()
      • pivoted_cholesky()
      • pivoted_cholesky2()
      • quaternion_to_rot_mat()
      • rmsd_grad()
      • rot_quaternion()
      • svd_inv()
      • sym_mat_from_tril()
      • sym_mat_from_triu()
    • 17.1.19. pysisyphus.linalg_affine3 module
      • augment_matrix()
      • augment_vector()
      • augment_vectors()
      • householder_reflection_matrix()
      • inv_translation_matrix()
      • plane_normal()
      • reflect_coords()
      • reflection_matrix()
      • rotation_matrix_for_rot_around_vec()
      • rotation_matrix_for_vec_align()
      • svd_plane_normal()
      • translation_matrix()
    • 17.1.20. pysisyphus.pack module
    • 17.1.21. pysisyphus.peakdetect module
      • peakdetect()
      • peakdetect_fft()
      • peakdetect_parabola()
      • peakdetect_sine()
      • peakdetect_sine_locked()
      • peakdetect_spline()
      • peakdetect_zero_crossing()
      • zero_crossings()
      • zero_crossings_sine_fit()
    • 17.1.22. pysisyphus.plot module
      • CDD_PNG_FNS
      • anim_cos()
      • get_en_conv()
      • get_force_unit()
      • list_h5_groups()
      • load_h5()
      • parse_args()
      • plot_afir()
      • plot_all_energies()
      • plot_calculations()
      • plot_cos_energies()
      • plot_cos_forces()
      • plot_cycle()
      • plot_gau()
      • plot_irc()
      • plot_irc_h5()
      • plot_md()
      • plot_opt()
      • plot_overlaps()
      • plot_scan()
      • plot_trj_energies()
      • render_cdds()
      • run()
      • spline_plot_cycles()
    • 17.1.23. pysisyphus.plot_ascii module
      • Grid
      • plot()
      • plot_wrapper()
    • 17.1.24. pysisyphus.run module
    • 17.1.25. pysisyphus.socket_helper module
      • get_fmts()
      • recv_closure()
      • send_closure()
    • 17.1.26. pysisyphus.testing module
      • DummyMark
      • available()
      • module_available()
      • using()
    • 17.1.27. pysisyphus.thermo module
      • get_thermoanalysis_from_hess_h5()
      • print_thermoanalysis()
    • 17.1.28. pysisyphus.timing module
      • RuntimeEstimation
      • estimate_runtime()
      • render()
    • 17.1.29. pysisyphus.trj module
    • 17.1.30. pysisyphus.typing module
    • 17.1.31. pysisyphus.version module
    • 17.1.32. pysisyphus.xyzloader module
      • coords_to_trj()
      • make_trj_str()
      • make_trj_str_from_geoms()
      • make_xyz_str()
      • make_xyz_str_au()
      • parse_trj_file()
      • parse_trj_str()
      • parse_xyz_file()
      • parse_xyz_str()
      • split_xyz_str()
      • write_geoms_to_trj()
    • 17.1.33. pysisyphus.yaml_mods module
      • get_constructor()
      • get_loader()
    • 17.1.34. Module contents

Indices and tables

• Search Page