6.4. QM box¶

In this page is presented how to select the parameter you want for the QM calculations using the QMParameter object. The ‘’important’’ part in $\texttt{FROG}$ relies in the electrostatic embbeding part, and maybe less in the other parameters. Indeed, $\texttt{FROG}$ has been built to handle for you the electrostatic emmebdding and provide several scheme, see this page. The rest of the parameter, such as the theoretical framework to solve the electornic Hamiltonian or the basis set, are also very important but are less difficult to use numerically speacking: $\texttt{DALTON}$ makes it easy.

Therefore, in this page is presented how to deal with the QM calculation options using the QMParameter object. Most of the attributes presented here are very ‘simple’: they will write in the $\texttt{DALTON}$ input file some lines. The $\texttt{DALTON}$ software provide an extensive and complete user manuel, where all the input are explained. We warmly recommand to read it to understand along with the dalton.dal file created by $\texttt{FROG}$ to understand the effect of some QMParameter attributes.

Note

For $\texttt{DALTON}$ veteran user/developers: the way $\texttt{FROG}$ handle the input has been dictacted by its initial use: DFT and hyperpolarizability calculation. Today no parameter are available to use a given ‘dalton.dal’ file, and thus bypass the actual architecture and limitations. If you need this behaviour please do not hesitate to contact us.

6.4.1. QMParameter Object ¶

If an optical property with the ‘QM’ calculation style in the OpticalParameter object is required, see this part, a QMParameter object should be provided in the OpticalParameter.qmparameter attribute.

To initialize a QMParameter object, first creat one:

from Frog.class_OpticalParameter import QMParameter
my_qmparameter = QMParameter()

Then, fill the attribute as usual for an object:

my_qmparameter.attribute_name = attribute_value

6.4.1.1. Presentation ¶

There are several QMParameter attributes, here are a list sorted by use:

Environment management:

QMParameter.calculation_style

QMParameter.pe_level

QMParameter.max_pe_distance_neigh

QMParameter.long_range_distance_switch

QMParameter.max_pe_polarization_distance_neigh

QMParameter.max_qm_box_distance_neigh

QMParameter.rcut_PE_direct

QMParameter.rcut_PE_smoth

QMParameter.ewald_factor

QMParameter.PE_k_vector_range

Quantum resolution scheme:

QMParameter.theory_lv

QMParameter.functional

Basis:

QMParameter.type_basis

QMParameter.global_basis_value

QM box properties:

QMParameter.total_charge

QMParameter.static_electric_field_direction

QMParameter.static_electric_field

Optical property:

QMParameter.polarizability_response

QMParameter.shg_response

Functionement parameters:

QMParameter.max_iter_scf

QMParameter.restart

QMParameter.write_xyz_environment

Note

Est ce que c est suffisement comprehensible en lisant la definition des attribues? Etant donne que pour l instant on n a pas beaucoup de choix, je n ai pas fait de sous-section ou j explique plus en details qui fait quoi. A voir?

6.4.1.2. Where are the information to write the input file?¶

Once you have provided the QMParameter for an MT, these parameters will be used to wrtie the $\texttt{DALTON}$ input file for all the molecule of this MT that should be QM-treated – thus for all the frame. Appart for very few parameter, like the electrostatic field (especially in the PE long scheme), the dalton.dal file will be similar for all the molecule of this MT. The molecule.mol file may be different for every configuration since the geometry are written in the laboratory frame. Finally, the potential.pot file, which contains the electrostatic environement, will be different for every configuration.

To write the dalton.dal file, $\texttt{FROG}$ uses mostly the parameter provided in the QMParameter object. To write the molecule.mol file, the basis are provided by the QMParameter object, while the geometry and the number of electrons are provided by the QMDescription object. The potential.pot file uses the QMParameter object and the ElectrostaticDescription of the neighborgs.

6.4.1.3. QMParameter Attributes ¶

QMParameter.calculation_style

Type [str]

The type of electrostatic embedding for the QM calculation of this MT.

3 types of embedding are available: ‘Vacuum’, ‘PE’, ‘PE long’ and ‘PE + QM’.

‘Vacuum’

Depreciated, use ‘PE’ with pe_level=-1 instead.

‘PE’

The electrostatic embedding scheme where each molecule are alone in their QM box – monomere QM calculation. The order used to described the electrostatic neighborgs is set by QMParameter.pe_level. The neighborhood is built up to a distance given by QMParameter.max_pe_distance_neigh.

If QMParameter.pe_level = 1, 3 areas are defined. If a neighborgs distance is less then QMParameter.max_pe_polarization_distance_neigh, this neighborgs is described using polarizability (and the other point charge, dipole ect…). After this distance, and until QMParameter.max_pe_distance_neigh, the neighborgs is described without polarizability. After QMParameter.max_pe_distance_neigh, the neighborgs does not contribute to the electrostatic environment of the target molecule.

Important note: you may define larger QMParameter.max_pe_distance_neigh then the MD box size. In this case, FROG will increase the neighborhood by using the PBC defines in GP.env_authorised_pbc_condition.

‘PE long’

Warning

In the current version, this method is no longer available. It has been replace by ‘PE’ with qmparameter.long_range_distance_switch attribute.

The long-range electrostatic embedding scheme where each molecule are alone in their QM box – monomere QM calculation.

In this case, all the molecule in the MD box contributes to the electrostatic environment. If there are within a distance of QMParameter.rcut_PE_direct, they contribute ‘directly’. Each neighbors are added in the potential dalton file and thus produce an heterogenous electric field within the QM box vinicity. For the molecule in the box but futher away, the electrostatic field generated by them at the ‘mean position’ of the target molecule is computed. All of these ‘long-range’ contribution are summed up and affects the QM calculation by adding an homogenous electrostatic field.

In top of these ‘long-range’ contribution of molecule in the box, periodic copy of the MD box are created using the QMParameter.PE_k_vector_range attribute. All the molecule, including the copies of the target one, contributes to the ‘long-range’ electrostatic field. This is done in the same spirit as long-range intermolecular interaction calculation in MD calculation, but without using the fourier space.

Warning

The order used to described the electrostatic neighborgs SHALL BE QMParameter.pe_level=0. Note because there is important argument against, but because it has not been tested yet.

Warning

The QMParameter.rcut_PE_direct has to be smaller then the MD box size!

Like in MD, you can use the QMParameter.rcut_PE_smoth and QMParameter.ewald_factor to creat a third area where the molecule contribute both to the direct and long-range part. Note that this functionality has not been widely tested.

‘PE + QM’

The electrostatic embedding scheme where the target molecule may be not alone in their QM box.

The neighborgs that are closer then QMParameter.max_qm_box_distance_neigh are added to the QM box. This mean that the QM calculation will have more atoms are more electrons.

Let’s say that the target molecule is Water, and that an Ethanol is added to the QM box. Questions arise if the parameter used to described the electronic part of one molecule is not the same as the other. For instance, if different basis are used, or different functional ect.. To deal with this problem, the GP.preference_functional can be used.

Warning

This ‘PE + QM’ option has not been extensively tested.

Note

If you are looking for a vacuum-like QM calculation, use QMParameter.calculation_style = ‘PE’ along with QMParameter.pe_level = -1.

QMParameter.pe_level

Type [int]

Set the Polarizable Environment of the neighborhood.

pe_level = -1: Vacuum

No contribution of the neigborgs.

pe_level = 0: static neighborgs

The neighborgs are described using point charge and/or dipole and/or quadrupole, as defined in their molecular library file. No polarizability.

pe_level = 1: polarizability

The neighborgs are described using point charge and/or dipole and/or quadrupole, as defined in their molecular library file, and mayby a polarizability. This means that the permanent dipole can be created at the neighborgs localization depending on the total neighborhood.

Warning

If the QMParameter.calculation_style = ‘PE long’, QMParameter.pe_level SHALL BE 0.

Note

The pe_level = 1 has not been extensively tested.

QMParameter.max_pe_distance_neigh

Type [float]

Parameter meaningfull only for QMParameter.calculation_style = ‘PE’ or ‘PE + QM’. For ‘PE long’, use QMParameter.rcut_PE_direct instead.

If QMParameter.pe_level = 0 or 1, set the maximal distance to add an electrostatic neighborgs. The neighbors is add without polarizabilities.

Warning

QMParameter.max_pe_distance_neigh is used to find all the neighbors in the first place. Therefore, QMParameter.max_pe_distance_neigh should be at least larger then QMParameter.max_pe_polarization_distance_neigh or QMParameter.max_qm_box_distance_neigh. If you want all the neighbors to be described with polarizabilities until a distance D, set QMParameter.max_pe_distance_neigh to D and MParameter.max_pe_polarization_distance_neigh to something larger then D.

Note

If QMParameter.pe_level is larger then the MD box, FROG uses the PBC condition defines in GP.env_authorised_pbc_condition to extend the accessible neighborhood by copying the QM box.

QMParameter.long_range_distance_switch

Type [float or str]

Parameter meaningfull only for QMParameter.calculation_style = ‘PE’.

Defined a distance after which the neighbors are not included explicitly in the PE environement. After this distance, the neighbors electrostatic field is computed at the target molecule ‘mean position’ in the laboratory frame. This contribution is added to all the other neighborgs after this distance, and closer than max_pe_distance_neigh. The total electrostatic field is added to the QM box as if it was an spatially homogenous field.

Note

If long_range_distance_switch > max_pe_distance_neigh nothing for the environment description.

Note

You can also defined an extra electrostatic field using static_electric_field and static_electric_field_direction. This field would be added to the one created by the long-range environment.

Warning

Today this scheme works only for PE level=0 and for point charge for the electrostatic description.

QMParameter.max_pe_polarization_distance_neigh

Type [float]

Parameter meaningfull only for QMParameter.calculation_style = ‘PE’ or ‘PE + QM’.

If QMParameter.pe_level = 1, set the maximal distance to add an electrostatic neighborgs which can be polarizable. The neigbors which will be described using polarizabilities should be closer then QMParameter.max_pe_polarization_distance_neigh. If neighbors are closer then QMParameter.max_pe_distance_neigh but futher away then QMParameter.max_pe_polarization_distance_neigh, they are described with no polarizabilities.

Note

If you want to describe all the neighbors using polarizabilities, set QMParameter.max_pe_polarization_distance_neigh > QMParameter.max_pe_distance_neigh.

QMParameter.max_qm_box_distance_neigh

Type [float]

Parameter meaningfull only for QMParameter.calculation_style = ‘PE + QM’.

If the distance between a neighbors and the target molecule is less then QMParameter.max_qm_box_distance_neigh, the neighbors is added to the QM box. Therefore, this neighbors is no longer in the ‘’electrostatic environment’’. It is the best way to add the effect of a neighbors to a target molecule because it will contain all the electrostatic and quatum effect.

However, it may be more difficult to understand the optical result obtained because they are no longer from a ‘’single molecule’’ but a graps of molecule.

Be aware that setting a large QMParameter.max_qm_box_distance_neigh will increase a lot the number of electron in the QM box, and therefore increase the QM calculation time.

In the more complexe environment case: QMParameter.calculation_style = ‘PE + QM’ and QMParameter.pe_level = 1. A molecule is added to the QM box if its distance from the target molecule is less then QMParameter.max_qm_box_distance_neigh. If it is not the case, it is added to the electrostatic environment using polarizability description if its distance is less then QMParameter.max_pe_polarization_distance_neigh. If it is not the case, it is added to the electrostatic environement without polarizability if its distance is less then QMParameter.max_pe_distance_neigh. If the neighbors is futher away, it does not affect the QM calculation.

Warning

The functionality has not been widely tested. Please take some time to check the dalton input created before running tons of calculation – especially if you have very long molecule!

QMParameter.rcut_PE_direct

Type [float]

Parameter meaningfull only for QMParameter.calculation_style = ‘PE long’. For ‘PE’ or ‘PE + QM’ use QMParameter.max_pe_distance_neigh instead.

Set the maximal distance to add an electrostatic neighborgs directly. The neighbors is add without polarizabilities.

Warning

The QMParameter.rcut_PE_direct should be smaller then the MD box size at any time! The QMParameter.calculation_style = ‘PE long’ was especially designed to avoid building large direct electrostatic environement!!! If you are uncertain about the radius to use, try out some value! You can also see the electrostatic field derivative generated by the long-range part to better understand the direct radius to use. See the electrostatic_field diagram.

QMParameter.rcut_PE_smoth

Type [float]

Parameter meaningfull only for QMParameter.calculation_style = ‘PE long’.

Used to defined a smothing radius thoughout which the neighborgs are added both in the direct and long-range part. If a nieghbors is within QMParameter.rcut_PE_direct from the target molecule, it is added directly in the Dalton potential file using the charge, dipole and quadrupole moment defined in its molecular library module. If a neighbors distance from the target molecule is between QMParameter.rcut_PE_direct and QMParameter.rcut_PE_smoth, it is added to the potential file but with a smaller charge, dipole and quadrupole moment. The rescaling factor used is given by the QMParameter.ewald_factor parameter:

rescaling_factor = np.exp(-(distance_from_target/qmparameter.ewald_factor)**2)

The direct part is rescaled using the rescaling_factor, the long range part using (1-rescaling_factor)

If a neighbors is futher away then QMParameter.rcut_PE_direct and QMParameter.rcut_PE_smoth, its contributes to the electrostatic environement by an homogenous electrostatic field - with its full charge, dipole and/or quadrupole moment.

Note

If you do not want to use this feature, set QMParameter.rcut_PE_smoth < QMParameter.rcut_PE_direct

Warning

This functionality has not been widely used. It may be usefull if you have ionic molecule where the electrostatic field generated is very strong. Or you can use a larger QMParameter.rcut_PE_smoth.

QMParameter.ewald_factor

Type [float]

Parameter meaningfull only for QMParameter.calculation_style = ‘PE long’.

Set the rescaling paramter used for the molecule within 0 < QMParameter.rcut_PE_direct < QMParameter.rcut_PE_smoth from the target molecule

The rescaling parameter is given by:

rescaling_factor = np.exp(-(distance_from_target/qmparameter.ewald_factor)**2)

The direct part is rescaled using the rescaling_factor, the long range part using (1-rescaling_factor)

QMParameter.PE_k_vector_range

Type [list of int]

Parameter meaningfull only for QMParameter.calculation_style = ‘PE long’.

Set the number of QM box to repeat in the given direction to add to the target molecule long-range electrostatic field. For each repated box, all the molecule contributes to the long range electorstatic field.

Example

QMParameter.PE_k_vector_range = [2, 2, 2]

This case representa a 3D PBC. Lets say the initial box is a 2x2x2nm box and that QMParameter.rcut_PE_direct = 10 Angstrom. One target molecule neighborhood is built up to 10 Angstrom. The found neighborgs contribute directly to the electrostatic environement with the dalton potential file. The rest of the molecule in the box contribute to the QM calculation by adding a homogenous electrostatic field.

Then, the box is reapeated 2 times in every direction, creating a 10x10x10nm box. Every molecule in this extended box contributes to the long-range part except the one that are within a radius of 1 nm. This include the periodic copy of the target molecule itself.

QMParameter.PE_k_vector_range = [3, 3, 0]

This case represents a 2D PBC. If the initial box is a 2x2x10m, the repeated one will be 14x14x10 nm.

Note

The obtained ‘’repeated box’’ is centered around the target molecule.

Note

This parameter can be completly different from the GP.env_authorised_pbc_condition. However, they represent more or less the same thing: what is the symetry of the system (bulk, plane ect…).

Note

Using many repetition can lead to a very high numerical cost. Try out small one and the obtained result before asking for large QMParameter.PE_k_vector_range value!

QMParameter.static_electric_field_direction

Type [str]

Parameter meaningfull only if a QMParameter.static_electric_field has been set.

Provide in which frame the electrostatic field given in QMParameter.static_electric_field is expressed. It can be either in the ‘Molecular’ frame, or the ‘Laboratory’ one.

The laboratory frame is quite straightforeward to understand: it represents an extra electric field which impact all the MD box.

The molecular frame may not reproduce any physical situtation. However, it is very handy to compute optical property using the Finite Field formalism.

Example

See the QMParameter.static_electric_field attribute

Note

To get the molecular electric field if QMParameter.static_electric_field_direction = ‘Molecular’:

static_electric_field_mol = toolbox.rotate_1st_order_tensor(rot_mat.T, QMParameter.static_electric_field)

QMParameter.static_electric_field

Type [str]

Add an homogenous electric field for every molecule of this MT during the QM calculation. The value is given in atomic unit. You can add an electric field in any direction in the laboratory or in the molecular frame. To select the frame, use the attribute QMParameter.static_electric_field_direction.

Example

QMParameter.static_electric_field_direction = ‘Laboratory’ QMParameter.static_electric_field = [0.003, 0.0001, 0]

An extra electric field is added along the direction X with amplitude 0.003 a.u., another in the Y direction with amplitude 0.0001 a.u. This electric field will be the same for all the molecule of this MT.

QMParameter.static_electric_field_direction = ‘Molecular’ QMParameter.static_electric_field = [0.0, 0.0, 0.0005]

An extra electric field is added along the molecular direction z with amplitude 0.0005 a.u. This electric field will be diferent for every molecule because it will depend on the molecular orientation.

Note

If you are using the QMParameter.calculation_style = ‘PE long’, for every molecule the long-range part is added by a very similar processus. You can use both QMParameter.calculation_style = ‘PE long’ and QMParameter.static_electric_field: each molecule will have an extra homogenous electric field which will be the sum of the one produced by the long-range environment, and one given for every molecule by QMParameter.static_electric_field.

Note

If you do not want to add an electrostatic electric field, do not initialize QMParameter.static_electric_field nor QMParameter.static_electric_field_direction.

QMParameter.theory_lv

Type [str]

Set the ‘theory level’ used for solving the electronic quantum problem.

Today, only the DFT framework is available in Frog. Not because the rest would arise important problem, Dalton is very powerfull and provide optical reponse for many framework, but because the Frog users do not need more at until today. Therefore, if you need to use other framework, please contact us – or code it directly in Frog: it will not be complicate!

DFT:

For DFT calculation, you need to provide to Frog the functionla you want to use, using the QMParameter.functional.

Example

For DFT:

QMParameter.theory_lv = ‘DFT’

Note

Please note that some theory level/functional cannot be used to compute optical properties in Dalton. Therefore, we strongly recommand to test new framework on very few molecule to make sure the QM calculation works.

Warning

If you are using the QMParameter.calculation_style = ‘PE + QM’, it would be easier to use the same framework for every MT.

QMParameter.functional

Type [str]

Parameter meaningfull only if QMParameter.theory_lv = ‘DFT’.

Set the functional to use for this MT. The name you give to this attribute will be directly written in the dalotn.dal Dalton file without more checking: it is up to you to use a valid Dalton functional name.

Example

QMParameter.functional = ‘Camb3lyp’

Note

Sadly, for some functional, Dalton may not be able to compute optical properties.

QMParameter.type_basis

Type [str]

Define the type of basis to use. This parameter was written originaly because you may want to chose a basis set for all the molecule, or for each atom.

Today, only ‘Global basis’ are implemented in Frog – every atomic orbital are described using the same general basis set. If needed, it would not be difficult to define basis set for every atom.

‘Global basis’

Every atomic orbital are described using the same basis set. To provide the basis set, use QMParameter.global_basis_value .

Example

QMParameter.type_basis = ‘Global basis’ QMParameter.global_basis_value = ‘d-aug-cc-pVTZ’

The basis ‘d-aug-cc-pVTZ’ (very large, indended for hyperpolarizability calculation) is used for all the atom of this MT.

QMParameter.global_basis_value

Type [str]

Parameter meaningfull only if QMParameter.type_basis = ‘Global basis’.

Defines the basis set to use for every atomic orbital.

The basis set is written written in the molecule.mol Dalton file without more checking: it is up to you to use a valid Dalton basis name.

QMParameter.total_charge

Type [int]

Add an extra charge to the molecule of this MT. By default, no charge is defined.

Example

QMParameter.total_charge = int(-1)

Defines an anionic molecule.

Note

If ionic molecular are defined in the molecular library file, it would be very likely that this property is already defined there. So check the qm_target_description function of the MT if a charge is already defined. The charge defined in the qm_target_description will overwrite the one defined in the parameter file if any.

QMParameter.polarizability_response

Type [list or bool]

Defines the frequency at which the polarizability of this MT should be recorded. The frequency are given in atomic unit. For every frequency required, a diagram is created where its last part of the name is the frequency. Moreover, a SingleMolecule attribute is also created for each frequency.

Example

QMParameter.polarizability_response = [0.0, 0.05686, 0.11372]

3 frequency are required: infinite wave-length (0 atomic unit), 800 nm (0.05686) and 400 nm (0.11372).

Warning

Today, the polarizability calculation can only be perform if hyperpolrizability calculation are required. The frequency available in the polrizability are limited by the one required in the hyperpolarizability calculation. Until now, Frog has been many used for hyperpolarizability calculation. Please contact us if you want to use only polarizability calculation.

Therefore, if you want to have these frequency for the polarizability, you have to set at least these one for the hyperpolarizability:

QMParameter.shg_response = [0.0, 0.05686]

QMParameter.shg_response

Type [list or bool]

Defines the frequency at which the first hyperpolarizability of this MT should be recorded. The frequency are given in atomic unit. The frequency are for the excitation wave-length: the created dipole oscilates at twice the frequency.

For every frequency required, a diagram is created where its last part of the name is the frequency. Moreover, a SingleMolecule attribute is also created for each frequency.

Example

QMParameter.shg_response = [0.0, 0.05686]

2 frequency are required: infinite wave-length (0 atomic unit) and 800 nm (0.05686).

QMParameter.max_iter_scf

Type [int]

Set the maximal SCF iteration for the electronic degree of freedom solving procedure.

By default set to 500

QMParameter.restart

Type [bool]

Originaly created to perform a restart calculation from a template electronic problem to reduce the QM cost.

Until today, this feature has not been used. Mainly because only small molecule have been used, and because the reponse part is more CPU-demanding then the electronic energy problem.

If you want to use this feature, please contact us. But keep in mind that in any case the response part will have to be compute for every molecule!

Warning

QMParameter.restart shall be False

QMParameter.write_xyz_environment

Type [bool]

Set if the electrostatic environment should be written in an .xyz file or not. By default set to False.

If set to True, a .xyz file is written at the location where the Dalton input and output are. It represent the direct electrostatic environement. You can open this file using VMD for instance.

Note

The default value is False to reduce the disk-space occupency. However, we warmly recommand to use this option at least at the beginingto check how the electrostatic emmebedding is performed

Note

If the option QMParameter.calculation_style = ‘PE + QM’ is used, you can have also access to the molecule that are no longer in the electrostatic environement, but in the QM box.

QMParameter.RUN_pe

Type [bool]

Not user defined

Attribute used to make the Frog excetution easier. Set to True if electrostatic envrionement are used. Related to the dalton.dal file, see dalton_manager_module.generate_inp_dal .

QMParameter.RUN_properties

Type [bool]

Not user defined

Attribute used to make the Frog execution easier. Set to True by default. Related to the dalton.dal file, see dalton_manager_module.generate_inp_dal .

QMParameter.RUN_integral

Type [bool]

Not user defined