LibTrans

The MOSpace Class

Default Spaces

The MOSpace class is designed to provide information about arbitrary subsets of MOs to the integral transformation class. Each unique subset of orbitals is assigned a single character name, to be used when requesting intgrals in libtrans. A number of pre-defined spaces exist as part of the MOSpace class:

boost::shared_ptr<MOSpace> MOSpace::occ;
boost::shared_ptr<MOSpace> MOSpace::vir;
boost::shared_ptr<MOSpace> MOSpace::all;
boost::shared_ptr<MOSpace> MOSpace::nil;
boost::shared_ptr<MOSpace> MOSpace::dum;

which take the labels 'O', 'V', 'A', 'n', and 'd', respectively. Whether frozen occupied and/or virtual are included in these default spaces depends on the way the LibTrans object is instantiated (see below). The Occ and Vir spaces are the occupied and virtual orbitals, all is the full MO space, nil is a null space used to define SOs, while dum is used for the auxiliary space in density fitting.

Custom Spaces

Arbitrary ranges of MOs can be constructed by defining the following:-

• label: The label is a single (unique) character to be used to refer to the subspace in transformations. Because alpha and beta spaces are referred to using upper- and lower-case labels, the custom labels cannot be related by a case change. Moreover, the label must be distinct from any of the default space labels defined above.

• orbitals: The orbital list is a simple vector of integers, containing the Pitzer-ordered (i.e., ordered by irrep first, then by energy within irrep) indices of the orbitals to include in the space.

• indices: [optional] A re-indexing array can be defined; if it is, it is used to specify the orbital number that should be assigned to each orbital in the orbitals array when IWL output is used. This array has no effect on DPD output so an empty vector may be passed in if IWL output is not required.

For example the following defines a new space (labelled 'X') containing orbitals 0, 4 and 8, which will be output as 0, 1, 2 with IWL:

std::vector<int> orbitals;
orbitals.push_back(0);
orbitals.push_back(4);
orbitals.push_back(8);
std::vector<int> indices;
indices.push_back(0);
indices.push_back(1);
indices.push_back(2);
boost::shared_ptr<MOSpace> custom_space(new MOSpace('X', orbitals, indices));

The above code is for RHF-type spaces. If the spaces differ between alpha and beta, a corresponding constructor exists which has the syntax

boost::shared_ptr<MOSpace> custom_space(new MOSpace('X', alpha_orbitals, alpha_indices, beta_orbitals, beta_indices));

The IntgralTransform Class

The IntegralTransform class can be used to generate integrals over arbitrary MO ranges, specified using MOSpace objects. Almost all details of the transformation are defined in the constructor. Details expected by the constructor include:-

• wavefunction: The wavefunction object containing the orbitals that will be used in the transformations.

• spaces: A vector of shared pointers to MOSpace objects. This should contain all possible spaces that may be involved in any transformations generated by the current object. It can be any mixture of default and custom spaces.

• transformation_type [optional]: The type of transformation to be performed; one of Restricted, Unrestricted or SemiCanonical. Default is Restricted.

• output_type [optional]: The output buffer type: one of DPDOnly, IWLOnly, or IWLAndDPD. Default is DPDOnly.

• mo_ordering [optional]: The ordering convention used to label the output integrals if IWL output is requested: one of QTOrder or PitzerOrder. Default is QTOrder.

• frozen_orbitals [optional]: Which orbitals are to be frozen within the default spaces. If set to None, no orbitals will be frozen, regardless of user input. The OccOnly will freeze occupied if the user requested frozen occupieds but will always include all virtual; the VirOnly similarly always includes occupied orbitals but obeys the user input for virtual. The OccAndVir option, which is the default, obeys user input for both occupied and virtual orbitals.

If we define a spaces vector containing the default 'all' space, as well as the custom 'X' space defined above, we can construct a new object:

std::vector<boost::shared_ptr<MOSpace> > spaces;
spaces.push_back(MOSpace::all);
spaces.push_back(custom_space);
IntegralTransform ints(wfn, spaces);

This can be used to generate the full set of MO integrals

ints.transform_tei(MOSpace::all, MOSpace::all, MOSpace::all, MOSpace::all);

or even integrals (in Mulliken (11|22) notation, also known as chemists' notation) containing a mixture of spaces:

ints.transform_tei(custom_space, MOSpace::all, MOSpace::all, MOSpace::all);

For DPD output, there is a convenience helper function provided that will provide the indices needed to access different combinations of subspaces. The DPD_ID() member of the IntegralTransform class will provide the appropriate integer descriptors for all possible pairs of spaces. To save typing, it's convenient to define a preprocessor macro to define it:

#define ID(x) ints.DPD_ID(x)

The above calls to transform_tei() will always generate DPD entries with the label "MO Ints (WX|YZ)", where W,X,Y and Z are the subspaces labels for the four indices. An upper case is used for alpha orbitals, while lower case indices are for beta spin. To initialize the buffer

    global_dpd_->buf4_init(&K, PSIF_LIBTRANS_DPD, 0, ID("[A,A]"), ID("[A,A]"),
              ID("[A>=A]+"), ID("[A>=A]+"), 0, "MO Ints (AA|AA)");

The ID("[A,A]") generates the full list of all pairs of MO orbitals, while ID("[A>=A]+") is restricted to permutationally unique pairs, including the diagonal (the + denotes that the quantity is symmetric with respect to index permutation). For an antisymmetric quantity the notation ID("[A>=A]-") should be used. In both cases, omitting the '=' indicates that the diagonal elements are not included.

To access the bra indices for the second transformation above, the syntax ID("[X,A]") can be used. The mointegrals plugin provides a working demonstration of the IntegralTransform class with DPD.