MOL

Purpose

An object representation of a molecule

Synopsis

This is the main module in TONTO. It is intenede to provide a quantum mechanocal repr4esentation of a molecule and all properties that can be interrogated from a molecule.

Special note

Because it is quite large, the module may be broken up into parts, each part being labelled by a particular working author. Thus for example, the current distribution contains mol_dylan, mol_daniel, mol_chris.

The main routine is mol_main and contains essentially just the read and process_input routines.

The online documentation may not work properly for routines which are under individual author names. Probably you should not be using these routines for production purposes.

Default input data order

There is no associated MOLVEC type; an input data order has not been defined.

Listing of keywords

assign_natural_orbitals

Assign the natural orbitals to the currently defined molecular orbitals.

atomic_roby_populations

Evaluate the atomic Roby populations.

atoms= ATOMVEC

Enter data for a list of ATOM's. That is, concerning the number, type, and position of atoms in the molecule.

Example:

atoms= {
    O1   0.0  0.0  0.0   o-sto3g
    H2   1.0  0.0  0.0   h-sto3g
    H    0.0  1.0  0.0   h-sto3g
}

  • It is efficient to only specify a basis_label. Later, the entire basis set can be specified using the basis_sets command.

  • The basis_sets keyword may be used before or after the atoms keyword.

  • Before a QM calculation can begin, every basis_label must correspond to a defined basis set.

  • Use "units angstrom" to specify coordinates in angstrom units.

  • Use the axis_system command to specify coordinates in crystal axis system

  • The default units for thermal_tensors is angstrom -2.

atoms_groups= GROUP

Specify a partition of the numbers from 1 to the number of atoms in the molecule.

  • The GROUP module does not exist yet, so this keyword is not documented in the standard way yet

  • This is used for nonintegacting-group Hartree-Fock calculations

  • Within curly brackets { and } use the keywords atom_group= followed by an INTVEC list of atom indices; use atom_range= or range= followed by an INTVEC(2) indicating the range of atom indices, inclusive; use group_charges= array to enter an INTVEC describing the charge of each group.

b_field= REALVEC(3)

Enter the cartesian components of an externally applied static magnetic field B.

  • The default value is (0,0,0)

  • It is assumed that B is in atomic units of flux.

  • This keyword is used for plots of the diamagnetic part of the current density.

basis_set_directory= STR

Enter a directory where basis sets for each atom may be found.

  • This keyword must come before any atoms= keyword if basis sets are to be entered for those atoms

  • You must also specify a basis_set_kind=

  • The default value is "./basis_sets"

  • Not all basis sets are available. See the basis_sets directory and the contents of each file there for the list of available basis sets

basis_set_kind= STR

Enter a the kind of basis set to be used.

  • This must correspond to an existing basis set file in the basis set directory

  • See basis_set_directory=

basis_sets= BASISVEC

Enter data for a list of basis sets for use in quantum chemical calculations.

Example:

basis_sets= {
{
    h-sto3g 
    {
      S   3
        3.42525091         0.15432897
        0.62391373         0.53532814
        0.16885540         0.44463454
    }

    o-sto3g
    {
      S   3
      130.70932000         0.15432897
       23.80886100         0.53532814
        6.44360830         0.44463454
      S   3
        5.03315130        -0.09996723    
        1.16959610         0.39951283  
        0.38038900         0.70011547 
      P   3
        5.03315130         0.15591627
        1.16959610         0.60768372
        0.38038900         0.39195739
    }
}

  • The basis_label need not correspond to any that are actually used in the atoms keyword.

canonicalize_mos

Generate a fock matrix from the existing molecule orbitals in memory and diagonalise it over the occupied part only, and the virtual part only, producing "canonical" molecular orbitals.

  • The orbitals need not be converged for the existing kind of SCF

  • See scfdata= and especially the scf_kind= within this derived data keyword

charge= INT

Enter the charge on the molecule in atomic units of charge.

  • The charge on the molecule is used to work out the total number of electrons, and with the spin multiplicity, the number of alpha and beta electrons.

create_cluster

Create a cluster from the existing set of molecule information.

  • This keyword is not documented in the standard way

  • Refer to the online documentation

crystal= CRYSTAL

Enter the data for specifying a crystal, including the experimental data for measured structure factors

delete_scf_integrals

Delete the integrals files for the previous SCF calculation.

  • This must be done whenever a new geometry is specified.

  • This command has an effect for direct calculations, because the one electron integrals are always stored on disk.

dftgrid= DFTGRID

Enter the data for specifying an integration grid for DFT functions.

e_field= REALVEC(3)

Enter the cartesian components of an externally applied static electric field E.

  • The default value is (0,0,0)

  • It is assumed that E is in atomic units of flux.

factor_density

Multiply certain atom basis set sized blocks of the density matrix by the specified factors

  • This keyword is not documented in the standard way

  • Refer to the online documentation

fit_thermal_parameters

Optimise the thermal parameters so as to minimise the χ2 for the predicted vs. the experimental structure factors

  • Crystal data must be entered, and there must be an existing density matrix

  • Refer to crystal=

force_thermal_symmetry

Force the thermal parameters on symmetry equivalent atoms to be equal. This is performed by averaging.

  • This keyword is undocumented

gauge_origin= REALVEC(3)

Enter the gauge origin for an externally applied static magnetic field.

  • The default value is (0,0,0)

  • This keyword will affect spin orbit and magnetic field calculations

get_atom_density

Read the stored sum of spherically averaged atom densities from the archive stored on disk into the current density matrix.

get_homoleptic_bond_index

Calculate the homoleptic bond index between two Roby fragments

  • This keyword remains undocumented

  • Refer to the online documentation

hf_scf_energy_gradient

  • Calculate the Hartree-Fock energy gradient

  • Warning: this keyword is untested

  • Can you debug it?

grid= PLOTGRID

Enter the data for specifying a rectilinear grid, for plots

make_ao_density_matrix

Make the density matrix in the AO basis set from the current density matrix. (If the current density matrix of of the restricted kind, no operation is performed).

make_ao_sz_density_matrix

Make the matrix of the Sz operator in the AO basis set from the current density matrix. This is used to generate densities for use in calculating spin-only magnetic structure factors from UHF calculations.

make_atom_density

Calculate the density matrix as a sum of spherically averaged atomic UHF densities.

  • The maximum multiplicity Hund's rule is assumed for the spin state of the atom.

make_fermi_mobility_grid

Make and print out the Fermi mobility function on the specified vibrationally rectilinear plot grid.

make_fock_guess

Make an initial set of molecular orbitals and eigenvalues from the current fock matrix.

make_fock_matrix

Make the fock matrix from a density matrix already in memory.

make_group_density_matrix

Make a density matrix which is the sum of non-interacting group densities

  • Refer to the atom_groups= keyword to define the groups

  • Only works for closed shell rhf group fragments at the moment

  • Can you fix the rest?

make_irrotational_jp_grid

Make and print out the irrotational part of the paramagnetic current density on the specified rectilinear grid.

make_mulliken_matrix

Make and print out the Mulliken population matrix.

make_natural_orbitals

Make the natural orbitals for the currently defined molecular orbitals.

make_pnd_scalar_magnetic_sf

Make the polarised neutron diffraction (pnd) scalar magnetic structure factors for the currently defined complex density matrix.

make_promol_density_matrix

Make a promolecule density matrix from symmetrically orthonormalised group molecular orbitals

  • The promolecule orbitals are also made, and are ordered by group, including the virtual orbitals within each group i.e. the occupation number vector is not continguous

  • Refer to atom_groups= and make_promol_density

  • Only works for rhf fragment groups at the moment

make_roby_atoms

Define the atomic natural orbitals for every atomn in the molecule

  • These are used to define the Roby aton projectors from Roby population analysis

make_scf_density_matrix

Make a density matrix from the current set of molecular orbitals, for the currently defined type of SCF calculation (set in scfdata).

make_structure_factors

Make the structure factors for the currently defined density matrix.

make_sz_structure_factors

Make the Sz spin only magnetic structure factors for the currently defined density matrix.

make_vib_averaged_rho_grid

Make and print out the vubrationally averaged charge density for a diatomic molecule using adpative Simpson quadrature.

make_weak_force_energy_shift

Calculate the parity violating weak force energy shift from a complex spin-orbit SCF calculation.

multiplicity= INT

Enter the spin multiplicity value for the molecule, 2S+1, where S is the spin of the molecule.

  • The multiplicity values is used to define the number of alpha and beta electrons in unrestricted Hartree-Fock (UHF) calculations.

name= STR

Input the name you wish to give to your molecule calculation.

  • The name= keyword must be the first one in any input file.

  • The value of the inputted string is used to define the start of archive file names, so do not use any spaces in it.

optimise_thermal_parameters= BIN

If set TRUE, the thermal parameters in an X-ray wavefunction fitting calculations are optimised to minimise the χ2 agreement statistic.

plot_covalent_orbitals INT

Output the Roby covalent orbital density for the specified orbital index.

plot_ionic_orbitals INT

Output the Roby ionic orbital density for the specified orbital index.

plot_subspace_density INT

Output the Roby subspace density for the specified shared orbitals whose index is specified.

pointgroup= CRYSTAL

Specify th pointgroup symmetry of the molecule in Schoenflies notation.

  • The character table does not include complex irreps, but they are grouped into two dimensional modules.

  • The character table is not available for the Icosahedral groups. used in the atoms keyword.

put

Put out information concerning the current molecule to the stdout TEXTFILE.

put_cluster_operations REAL

Put the crystal Seitz operations which will generate a cluster for which no atom is more than a certain specified distance from the center of the molecule out to the stdout TEXTFILE.

put_crystal

Put out CRYSTAL information for the current molecule to the stdout TEXTFILE.

put_all_atom_coord_info

Put out all the atom coordinate information.

put_ao_energy_partition

Put out the AO energy partition, which is a kind of Morokuma analysis

  • This is only available for two rhf fragment groups at the moment

  • The density matrix for each group is partitioned according to AO basis functions, and then the energy of each block os calculated separately, including the "interaction energy" EAB = E - EAA - EBB

  • Refer to put_sao_energy_partition and put_mo_energy_partition

  • Refer to atom_groups= command

  • Refer to make_promol_density_matrix and make_group_density_matrix command

put_chi2_vs_angle_plot

Make a gnuplot table of the χ2 agreement statistic between calculated and experimental structure factors, and the binned sin &thetas;/λ values, where λ is the diffraction particle wavelength

  • This may be moved to the CRYSTAL module at a later date

put_cluster_input

Write out the cluster input details for a supercluster of the existing molecule

  • This keyword remains undcoumented

  • Refer to the online documentation

put_crystal

Put out all crystal information for this molecule

put_crystal_reflection_data

Put out only crystal reflection information for this molecule

  • This may be moved to the CRYSTAL module at a later data

put_current_time

Put the current time out to the stdout TEXTFILE.

put_density_matrix

Put out the density matrix to the stdout.

put_fock_matrix

Put out the fock matrix to the stdout.

put_f_calc

Put the calculated structure factors out to the stdout.

put_f_calc_plots

Put out a series of useful gnuplot files detailing the behaviour of the calculated structure factors

  • It produces the normalised deviates vs. sin&thetas;/λ; the normalised deviates vs. experimental structre factor magnitude; the normalised deviates vs. experimental structre factor magnitude; both of the above plots when the calculated structure factors include an extinction correction; and the mean value of the normalised deviate with and without extinction

put_fock_matrix

Put out the fock matrix to the stdout.

put_g_tensor_information

Calculate and put out the g tensor information from an existing complex density matrix.

put_labelled_qq_plot

Write an archive of the QQ plot for the calculated structure factors data, including the h, k, l reflection data

  • This is a plot of the sorted experimental quantile versus the expected gaussian quantile

  • Refer to put_qq_plot

put_mos_and_energies

Put out the molecular orbitals and orbitals energies to the stdout.

put_molecular_orbitals

Put out the molecular orbitals information to the stdout.

put_mo_energy_partition

Put out the MO energy partition, which is a kind of Morokuma analysis

  • This is only available for two rhf fragment groups at the moment

  • The density matrix for each group is partitioned according to MO basis functions, and then the energy of each block os calculated separately, including the "interaction energy" EAB = E - EAA - EBB

  • Refer to put_ao_energy_partition and put_sao_energy_partition

  • Refer to atom_groups= command

  • Refer to make_promol_density_matrix and make_group_density_matrix command

put_sao_energy_partition

Put out the symmetrix AO energy partition, which is a kind of Morokuma analysis

  • This is only available for two rhf fragment groups at the moment

  • The density matrix for each group is partitioned according to MO basis functions, and then the energy of each block os calculated separately, including the "interaction energy" EAB = E - EAA - EBB

  • Refer to put_ao_energy_partition and put_mo_energy_partition

  • Refer to atom_groups= command

  • Refer to make_promol_density_matrix and make_group_density_matrix command

put_scf_energy

Evaluate and put out the SCF energy

  • The kinetic energy is also outputted for information

  • Refer to scfdata= to set scf type

put_scf_energy_in_mo_pairs

Evaluate and put out the SCF energy in an MO pairs like form

  • This decomposes the total SCF energy into one orbital in two orbital contributions in the expected way

put_plotgrid

Put out the plotgrid information

  • Refer to plotgrid= to set the plot information and plot type

  • Refer to plot to actually perform the plot calculation

put_pnd_sf

Put out the polarised neutron diffraction (PND) structure factor information to the stdout.

put_pointgroup

Put out POINTGROUP information for the current molecule to the stdout.

put_qq_plot

Put the data for Hamilton's $QQ$ plot out to the stdout.

  • This is a plot of the sorted experimental quantile versus the expected gaussian quantile

  • Refer to put_labelled_qq_plot

put_roby_atom_energy

Put out the Roby energies for every atom

  • This keyword is undocumented

  • Refer to the online documentation

put_roby_ionic_energy

Put out the Roby ionic energies for every atom

  • This keyword is undocumented

  • Refer to the online documentation

put_roby_shared_energy

Output the Roby shared energy.

  • This keyword is undocumented

  • Refer to the online documentation

put_roby_shared_population

Output the Roby shared populations.

  • This keyword is undocumented

  • Refer to the online documentation

put_sylvian_csizmadia_tensors

Output an approxintmation for the polarisability and hyperpolarisability tensors developed by Sylvian and Csizmadia.

put_scf_energy_in_mo_pairs

Calculate and put out the SCF energy in molecular orbitals pairs for the current set of molecular orbitals.

put_time_taken

Put the time taken since the start_timer command (or beginning of job, if the start_timer command is not present) to the stdout.

put_total_time

Put the total time since the start_timer command (or the beginning of job, if the start_timer command is not present) out to the stdout.

put_vrml

Put out a VRML graphics representation of the molecule

read_archive STR STR

Read the specified binary archive, and its kind, into the program.

  • Only the possibilities molecular_orbitals, density_matrix, natural_orbitals, occupation_numbers and fock_matrix are allowed.

  • The kind must be one of the OPMATRIX kind types.

read_ascii_archive STR STR

Read the specified ASCII archive into the program.

  • Only the possibilities molecular_orbitals, density_matrix, natural_orbitals, occupation_numbers and fock_matrix are allowed.

  • The kind must be one of the OPMATRIX kind types.

  • This command is useful for inputting data from other programs: simply rename the input into the appropriate archive file.

read_g94_checkpoint_file

Read the gaussian94 checkpoint file, generated from the fchk command, into TONTO.

  • Atom positions, basis sets, molecular orbitals and density matrices are inputted.

redirect STR

Redirect the stdin to the name of the following input file

  • To come back to the original input file, use the revert command

  • See the revert command

roby_energy_analysis

Perform a Roby energy analysis on the previously calculated density matrix.

  • This keyword remains undocumented

  • Refer to the online documentation

roby_population_analysis

Perform a Roby population analysis on the previously calculated density matrix.

  • This keyword remains undocumented

  • Refer to the online documentation

scf

Perform an SCF calculation using the specified scfdata.

  • At the termination of the program the density matrix, molecular orbitals, and fock matrix hold the converged results for future calculations.

  • The results are also stored in archive files on disk for later use.

  • If a standard SCF calculation is performed, the integrals are stored ion disk and reused, if required.

scfdata= SCFDATA

Enter the data for the SCF calculation options, including the type of SCF, the initial guess, the convergence criteria, extrapolation methods, to name a few.

  • This does not perform a calculation. Only the required options are set. Use the scf keyword to invoke the SCF calculation.

simulate_new_f_exp

Add a series of σ-variance gaussian random deviates to the experimental crystal structure factors

  • This may be moved to the CRYSTAL module at a later date

start_timer

Start timing the program from the current point.

write_archive STR

Write the specified binary archive into the program.

  • Only the possibilities molecular_orbitals, density_matrix, natural_orbitals, occupation_numbers and fock_matrix are allowed.

  • The kind is determined from the current type of object which is to be written.

write_ascii_archive STR

Write the specified ASCII archive into the program.

  • Only the possibilities molecular_orbitals, density_matrix, natural_orbitals, occupation_numbers and fock_matrix are allowed.

  • The kind is determined from the current type of object which is to be written.

write_wfn_file

Write out a MORPHY98 .wfn input file.

  • This is useful for performing a Bader analysis on the current density matrix.