5.2. Diagram available¶

Reminder: The user-input have at least 3 parameters:

[analysis_type, geometrical_discretization, [N]]

Where ‘analysis_type’ is one of the analysis presented here (‘density’ or ‘alpha’ for instance: no capital letter), ‘geometrical_discretization’ is the discretization (‘Averaged’ or ‘Plane_xy’ for instance, see this page) and ‘N’ refers to the bin number used for the geometrical discretization. In all the documentation, ‘N’ refers always to the geometrical discretization, and is always the first element of the list defined as the third argument.

More parameters and bin number can be set after this minimal basis. For instance:

['beta', 'Plane_xy', [100, 50], [-20, 20]]

Here N = 100.

Warning

If several diagram for the same analysis are required, please note that no extra single molecule attribute are generated (in most of the case). This mean that the calculation of the individual property will be made according to the first diagram of this analysis type. Therefore, if in the input parameter some parameter are declared which impact directly the single molecule parameter value, this parameter should be the same for all the diagram declared. For instance the H-bond where the last user-input impact directly the individual H-bond value!

5.2.1. Density ¶

class Frog.class_Diagrams.Dia_density(sdparameter)[source]

Unit [Molecule / Angstrom^3]

Input format:

['density', geometrical_discretization, [N]]

Compute the density of the system for a given molecule type. Please note that the position of a molecule is defined in its molecular module using the function: compute_mean_position. In case the position of a molecule is ouside the box, it is reput inside for the diagram calculation. Very few extra calculation is required to perform the density analysis since the mean position of every molecule is computed anyway.

For the density, no extra parameters are needed, i.e., only the three basic arguments are needed to define the density analysis.

Diagram size: N

Diagram mean: No mean available

SingleMolecule attribute: mean_position

Extra parameter for the SingleDiagramParameter: Nothing

Example

User input:

[['density', 'Averaged', [1]],
['density', 'Plane_xy', [100]]]

Creates 2 diagrams:

One with name ‘density’, not space-discretized. Contains the number of molecule divided by the volume of the box.

One with the name ‘density_slice_z’, duscretized along the z-axis with 100 bins. The diagram.value contains the list of the number of molecule found per slices divided by the slice volume. Please note that the slice volume may depend on the MD box size.

5.2.2. Molecular Orientation ¶

class Frog.class_Diagrams.Dia_molecular_orientation(sdparameter)[source]

Unit [Projection]

Input format:

['molecular_orientation', geometrical_discretization, [N, M], Proba_style]

Compute the molecular orientation of a molecule type. This ‘’molecular orientation’’ is defined in its molecular module using the function named: compute_molecular_orientation. The molecular orientation can have an arbitrary number of values. For instance, it can be defined by 3 number (for instance 3 cosinus value). The expected value of a molecule orientation is between -1 and 1.

Depending on the Proba_style used, the size of the diagram is different. If Proba_style = ‘join’, the diagram compute the joint occurence for every dimension used to describe the molecular orientation. If L number of dimensions is needed, the diagram size is: NxMxMxM…xM with L times M. If Proba_style = ‘independent’, the diagram compute the independence for every dimension used to describe the molecular orientation. If L number of dimensions is needed, the diagram size is: NxLXM

Diagram size: NxLxM or NxMxM…xM

Diagram mean: NxL any case

SingleMolecule attribute: molecular_orientation

Extra parameter for the SingleDiagramParameter:

proba_style

Example

User input:

[['molecular_orientation', 'Plane_xy', [60, 45], 'join'],
['molecular_orientation', 'Plane_xz', [70, 10], 'independent']]

Let’s assume there is 3 number are needed to defined the molecular angle. Creats 2 diagrams:

One with name ‘molecular_orientation_slice_z’. Contains the join probability of finding the molecular orientation. Its size is 60x45x45x45. It mean size is 60x3.

One with name ‘molecular_orientation_slice_y’. Contains the independent probability of finding the molecular orientation. Its size is 70x3x10. It mean size is 70x3.

5.2.3. Hydrogen bond ¶

class Frog.class_Diagrams.Dia_hbond(sdparameter)[source]

Unit [H-bond]

Input format:

['hbond', geometrical_discretization, [N, I, J], partner, fct_parameters]

Compute the ‘’hydrogen bonds’’ of a molecule type with another molecule type – the ‘’partner’’ molecule type. This ‘’hbond’’ is defined in its molecular module or in the partner molecular module using the function named: compute_hbonds. This function should return whether one molecule or the other ‘’own’’ or ‘’give’’ something – for instance an hydrogen bond. This function can be of course used to defined other things then hydrogen bounds.

The important point is that this function should return only +1 for one of the molecule or 0 for both molecule. The diagram tracks the occurence of this molecule to ‘’own’’ or ‘’give’’ somthing with the other molecule type (joint occurence). Therefore, in the input the partner molecule type have to be defined.

I and J are the maximal number of ‘own’ and ‘given’ hbond respectively by this MoleculeType. The ‘mean’ is the independent average of the ‘own’ and ‘given’ hbond.

The last parameter, fct_parameters, depends on the function defined on the molecular module compute_hbonds. Please, keep in mind that the function compute_hbonds can be either defined in this molecular module or in the partner molecular module for the specific couple of molecule type.

Diagram size: NxIxJ

Diagram mean: Nx2

SingleMolecule attribute: hbond_ + partner

Extra parameter for the SingleDiagramParameter:

partner = [string] The moleculartype name of the partner molecule.
which_function_to_call = [string] Either ‘Target’ or ‘Partner’ if the compute_hbonds should be used in this molecular module or the partner one.
fct_parameters = [list] An array of all the parameter to pass to the function which compute the hbounds. See the molecular module function compute_hbonds to now what is expected.
max_distance = [float] Define the radius to defined the neighbourood.

Example

User input:

['hbond', 'Averaged', [4, 5],  'WaterTIP4P2005', [2.7, 37]]

The diagram size will be 4X5. The ‘partner’ MoleculeType name is WaterTIP4P2005. If there is no WaterTIP4P2005 declared, there will be zero hbond. If no ways of computing hbond between this MT and WaterTIP4P2005 are found in the compute_hbonds function of this molecular file module or the one of WaterTIP4P2005, Frog will krash. [2.7, 37] are the parameters passed to the molecular module function compute_hbonds.

5.2.4. Radial Distribution Function ¶

class Frog.class_Diagrams.Dia_rdf(sdparameter)[source]

Unit [Molecule]

Input format:

['rdf', geometrical_discretization, [N, M], partner, max_distance]

Compute the radial distribution function (rdf) of a target molecule type – the ‘’partner’’ molecule type – with respect to this molecule type. The distance between each molecule is defined between their ‘mean position’ – defined in their respective compute_mean_position function of their molecular module. The maximal distance to compute this rdf is set by max_distance, in Angstrom.

Note that the rdf obtained is not normalized. See the get started tutorial for more information.

Diagram size: NxM

Diagram mean: Not defined

SingleMolecule attribute: rdf_ + partner

Extra parameter for the SingleDiagramParameter:

partner = [string] The moleculartype name of the partner molecule.
max_distance = [float] Define the maximal radius for the rdf.

Example

User input:

['rdf', 'Averaged', [25],  'WaterTIP4P2005', 10.2]

The diagram size will be 25. The ‘partner’ MoleculeType name is WaterTIP4P2005. The maximal distance to find this partner is 10.2 Angstrom.

5.2.5. Electric Field ¶

class Frog.class_Diagrams.Dia_electric_field(sdparameter)[source]

Unit [V/A]

Input format:

['electric_field', geometrical_discretization, [N, M], [e_min, e_max] calculation_type, max_distance]

Compute the electrostatic field created by the environment around each molecule of this MT. This electrostatic environment takes into account every molecules (include this MT and others). Each neighborgs are described using their electrostatic description provided by their MT module.

The electrostatic field they produce are computed only at the ‘mean position’ of the molecule from this MT. The return electrostatic field is the one produce by all the environment (direct sum). The spatial derivative is also computed from the individua neighborgs contribution.

The results is written in Volt per Angstrom for the electrostatic field, and Volt per Angstrom square for the electrostatic field space derivative.

Depending on the calculation_type used, the size of the diagram may be different.

If calculation_type = ‘on_fly’, the diagram compute by itself the electrostatic field. It builts the neighborghood up to the max_distance parameter, convert it into electrostatic environment, and compute the net electrostatic field.

If calculation_type = ‘PE’, the diagram do not compute the electrostatic field by itself. In this case, an optical property analysis which require an PE environement should be ongoing. During the preparation of the QM run (in the ‘first part’ of $\texttt{FROG}$ procedure), the total electrostatic field is also stored in this diagram. Hence, the parameters used to built the environment DO NOT DEPEND ON THIS DIAGRAM but on the optical parameters. More precisely, it depends on the qmparameters used.

Especially, if the division between explicite (or ‘short’) and implicite (or ‘long-range’) is required, the dimensions of the electric_field diagram is increased to store the short and long part. See this tutorial for more informations.

The minimal size of the diagram is: 2x?x12. The first 2 are for the laboratory or molecular frame. The ? is for the direct and long part if needed. The last 12 are for the electrostatic field and its spatial derivative.

The parameters [e_min, e_max] is used to fix the minimal and maximal value to compute the distribution. Along with the number of M, it creats bins of length: (e_max-e_min)/M.

Diagram size: Nx2x12xM or Nx2x2x12xM

Diagram mean: Nx2x12 or Nx2x2x12

SingleMolecule attribute: electric_field_ + calculation_type

Extra parameter for the SingleDiagramParameter:

min_max = [list of two float] The maximal and minimal value to discretize each component of the vector.
calculation_type = [string] Can be ‘PE’ or ‘on_fly’. If PE is asked, it will be calculated using the PE environment. If ‘on_fly’ it will be computed independently according to the parameter given
max_distance = [float] Define the radius to built the neighbourood used to compute the electric field. This argument should not be defined if calculation_type = ‘PE’ and should be defined if calculation_type = ‘on_fly’.

Example

User input:

[['electric_field', 'Averaged', [1, 14], [-10, 10], 'on_fly', 10.5],
['electric_field', 'Averaged', [1, 17]], [-10, 10], 'PE']]

It creats 2 diagrams.

electric_field_on_fly: size of 2x12x14. The electrostatic environment around each molecule of this MT is built up to 10.5 Angstrom.

electric_field_PE: size 2x12x17 is the electrostatic environment used for this MT is classic, 2x2x12x17 if there is a short-long separation.

5.2.6. Alpha ¶

class Frog.class_Diagrams.Dia_alpha(sdparameter)[source]

Unit [atomic unit]

Input format:

['alpha', geometrical_discretization, [N, M], [min, max]]

Compute the polarizability of the molecule type in the molecular frame. The argument to define how the value are optained are defined in the optical parameters, see this page or this tutorial.

Note that if no QM calculation are performed, i.e. fixed alpha for all the molecule, this diagram has no sens and is ignored: every molecule share the exact same value!

All the optical properties are in atomic unit and also the alpha components. The min/max value given are used to performed distribution and are applied for every tensor components. Note that these extrema value do not impact the mean and standard deviation calculation.

Diagram size: Nx9xM

Diagram mean: Nx9

SingleMolecule attribute: alpha_ + frequency

Extra parameter for the SingleDiagramParameter:

min_max = [list of two float] The maximal and minimal value to discretize each component of the tensors.
frequency = [float or string] The frequency at which the tensor is computed. If no frequency is set (or a reference value), the frequency value is replace by ‘REF’. The frequency is fixed by the optical parameters definition.

Example

User input:

['alpha', 'Averaged', [1, 30], [-15, 15]]

will return an 9 X 30 diagrams. The ‘9’ is because their are 9 components for this tensor.

5.2.7. Iota ¶

class Frog.class_Diagrams.Dia_iota(sdparameter)[source]

Unit [atomic unit]

Input format:

['iota', geometrical_discretization, [N, M]article, [min, max]]

Compute the polarizability of the molecule type in the laboratory frame. The argument to define how the value are optained are defined in the optical parameters, see this page or this tutorial.

All the optical properties are in atomic unit and also the iota components. The min/max value given are used to performed distribution and are applied for every tensor components. Note that these extrema value do not impact the mean and standard deviation calculation.

Diagram size: Nx9xM

Diagram mean: Nx9

SingleMolecule attribute: iota_ + frequency

Extra parameter for the SingleDiagramParameter:

min_max = [list of two float] The maximal and minimal value to discretize each component of the tensors.
frequency = [float or string] The frequency at which the tensor is computed. If no frequency is set (or a reference value), the frequency value is replace by ‘REF’. The frequency is fixed by the optical parameters definition.

Example

User input:

['iota', 'Averaged', [1, 30], [-15, 15]]

will return an 9 X 30 diagrams. The ‘9’ is because their are 9 components for this tensor.

5.2.8. Beta ¶

class Frog.class_Diagrams.Dia_beta(sdparameter)[source]

Unit [atomic unit]

Input format:

['beta', geometrical_discretization, [N, M], [min, max]]

Compute the first hyperpolarizability of the molecule type in the molecular frame. The argument to define how the value are optained are defined in the optical parameters, see this page or this tutorial.

Note that if no QM calculation are performed, i.e. fixed beta for all the molecule, this diagram has no sens and is ignored: every molecule share the exact same value!

All the optical properties are in atomic unit and also the alpha components. The min/max value given are used to performed distribution and are applied for every tensor components. Note that these extrema value do not impact the mean and standard deviation calculation.

Diagram size: Nx27xM

Diagram mean: Nx27

SingleMolecule attribute: beta_ + frequency

Extra parameter for the SingleDiagramParameter:

min_max = [list of two float] The maximal and minimal value to discretize each component of the tensors.
frequency = [float or string] The frequency at which the tensor is computed. If no frequency is set (or a reference value), the frequency value is replace by ‘REF’. The frequency is fixed by the optical parameters definition.
beta_type = [str] The type of first hyperpolarizability. Either ‘dipole-dipole’, ‘dipole-quadrupole’ or ‘quadrupole-dipole’. It affects the size of the diagram (and the attached SingleMolecule property) and how is read the tensor from the DALTON output file. See this tutorial for more informations.

Example

User input:

['beta', 'Averaged', [1, 30], [-15, 15]]

will return an 27 X 30 diagrams, in the usual dipolar approximation. The ‘27’ is because their are 27 components for this tensor. At the quadrupole level, some diagram (dipole-quadrupole and quadrupole-dipole) will have 3x3x3x3=81 components instead of 27.

5.2.9. Chi ¶

class Frog.class_Diagrams.Dia_chi(sdparameter)[source]

Unit [atomic unit]

Input format:

['chi', geometrical_discretization, [N, M], [min, max]]

Compute the first hyperpolarizability of the molecule type in the laboratory frame. The argument to define how the value are optained are defined in the optical parameters, see this page or this tutorial.

All the optical properties are in atomic unit and also the alpha components. The min/max value given are used to performed distribution and are applied for every tensor components. Note that these extrema value do not impact the mean and standard deviation calculation.

Diagram size: Nx27xM

Diagram mean: Nx27

SingleMolecule attribute: chi_ + frequency

Extra parameter for the SingleDiagramParameter:

min_max = [list of two float] The maximal and minimal value to discretize each component of the tensors.
frequency = [float or string] The frequency at which the tensor is computed. If no frequency is set (or a reference value), the frequency value is replace by ‘REF’. The frequency is fixed by the optical parameters definition.
beta_type = [str] The type of first hyperpolarizability. Either ‘dipole-dipole’, ‘dipole-quadrupole’ or ‘quadrupole-dipole’. It affects the size of the diagram (and the attached SingleMolecule property) and how is read the tensor from the DALTON output file. See this tutorial for more informations.

Example

User input:

['chi', 'Averaged', [1, 30], [-15, 15]]

will return an 27 X 30 diagrams, in the usual dipolar approximation. The ‘27’ is because their are 27 components for this tensor. At the quadrupole level, some diagram (dipole-quadrupole and quadrupole-dipole) will have 3x3x3x3=81 components instead of 27.