7. Frog package¶

7.1. Subpackages¶

7.1.1. Frog.Molecules package

7.2. Submodules¶

7.3. Frog.check module¶

Frog.check.check_GP_env_authorised_pbc_condition(GP)[source]¶: Check what PBC direction have been authorised for building the environment

Frog.check.check_file_write_read(name_file, message_to_write)[source]¶: This function write on the file ‘name_file’ the message ‘message_to_write’. Then, it tries to read it and check that the message in retrived. This function have been tested for simple messages (no ‘n’ !!). This function goes with GlobalParameter.check_GP and help checking the GlobalParameter value after reading the input file.

Frog.check.check_name_diagram_uniqueness(L_diagram)[source]¶: Check if the name of the diagram are unique. Otherwise we can have big troubles later on

Frog.check.is_it_python_file(file)[source]¶: Verification if the file has a .py format.

7.4. Frog.class_DiagramParameter module¶

class Frog.class_DiagramParameter.DiagramParameter[source]¶

Bases: object

property IS_density¶

Type [bool]

Shortcut to help Frog know which analysis should be performed. There is as many IS_ + analysis type as analysis type. For instance IS_density or IS_alpha. If this analysis is required, set to True, otherwise set to False.

property IS_rot_mat¶

Type [bool]

Shortcut to help Frog know if the ‘rotational matrix’ for this MT should be computed. Many analysis required this matrix, therefore it is set not during the diagram initialization but later on during the checks, see Frog.class_molecule.end_initialize.

property L_allowed_molecule¶

Type [list]

Defined for each time step. Contain the molecule of this MT which should be treated according to the special_selection defined. If not special_selection is set, all the molecule can be treated.

Note

For advance user: The logging.info has been disable for this attribute because too much print would be done: the list of all the molecule to compute for every time step. For debug sake, you can use the logging of this attribute setter, or in the first_part.treat_one_frame function (maybe better in the first_part.treat_one_frame because you can print more meaningfull info along with this list).

property L_diagram¶

Type [list]

All the Single Diagram Parameter object relative to the diagrams declared. See Single Diagram Parameter object for more information.

Note

The number of analysis to performed is given by the function DiagramParameter.nbr_analysis – which is just len(L_diagram).

property L_possible_diagram¶

Type [list]

All the possible value of analysis/diagrams available in the code. Please note that if you want to develop another type of analysis, you have to add the name of the analysis in this list and also add a subclass of Diagram with the name: Dia_<your analysis name >. The way the subclass name is defined with the analysis name given in the function Frog.class_module.give_class_diagram_name.

nbr_analysis()[source]¶: Return the number of analysis to perform

read_diagram_input(GP, smparameter, L_diagram_analysis_to_perform, special_selection)[source]¶

Initialized the Diagrams for this molecule type: read the input and update the moleculetype.mtparameter.dparameter object.

The GP is used to have the simulation box sizes.

L_diagram_analysis_to_perform is a list of the different input for the different type of analysis. Note that every types of analysis have its specific input, but the minimal input is: [‘type of analysis’, ‘how the space is discretize’, ‘numbre of bins’ …].

property special_selection¶

Type [bool or list]

The single diagram parameters defines which analysis should be performed to this MT, and how.

This attribute defines which molecule of this MT should contribute to the analysis. The advantage is to speed up the calculation time: you may not be interested by all the molecules! Note that this selection applies to all the diagrams of this MT.

The format of this attribute is very similar to the geometrical discretisation option when declaring a diagram. As an user, when adding a new list of diagram to performed, you can define this special geometrical selection using:

myMT.read_diagram_input(GP, L_diagram_analysis_to_perform, special_selection=my_special_selection)

Here are the available values for my_special_selection:

False or True:

No extra special selection is made. All the molecule of the MT contributes to all the analysis and diagrams.

In this case, the DiagramParameter.special_selection object is set to False.

[‘All’]:

No extra special selection is made. All the molecule of the MT contributes to all the analysis and diagrams.

In this case, the DiagramParameter.special_selection object is set to False.

[‘Plane_ij’, bin_number, list_of_bin]:

For each time step, the box is discretized along plane with the axis ij. bin_number number of bin is used. Every molecules are assigned to one of these bin according to there mean position. If this bin is within the list_of_bin, the molecule is analyse.

In this case, the DiagramParameter.special_selection object is set to [axis where the space is decretize (0, 1 or 2), bin_number, list_of_bin]

[‘Layer’, nbr_layer, list_layer]:

For each time step, the molecule are assigned to a layer, using ‘nbr_layer’ number of layer. If a molecule is in the layer number given by list_layer, it is treated analysis by Frog. Otherwise not.

In this case, the DiagramParameter.special_selection object is set to [10, 2*nbr_layer+1, list_layer]

Example

my_special_selection = [‘Plane_xy’, 100, [60, 61, 62, 63, 64, 65, 66]]

The box in discretize along the z axis using 100 bins. Only the molecule within the 60 to 66 bin are analysed. Note that the list of authorized bin can not be continous.

Example

my_special_selection = [‘Layer’, 4, [-4, -3, 0, 1, 4]]

Here, nbr_layer = 4. A molecule can be assigned to the layer number 4, 3, 2 or 1 for the upper interface (the 1st is the closest to the bulk phase, the 4th the farthest), to -4, -3, -2, -1 for the lower interface (the -4 is the farest from the bulk phase) or to 0 for the molecule in the bulk-like phase. Only molecule with layer number -4, -3, 0, 1 or 4 will be treated by Frog.

Note

This condition is made before the one regarding the QM calculations parameters. If QM calculation should be made, a molecule has to respect both conditions (given in special_selection and the optical parameter parameters).

Note

If a diagram uses a Plane type discretization and with the same direction as special_selection, then the diagram size will be modified. Indeed, one major use of this attribute is to reduce the size of the diagram. For example, if a Plane_xy with 100 bins is required for a digram, and my_special_selection = [‘Plane_xy’, 100, [60, 61, 62, 63, 64, 65, 66]], the size of the diagram object attributes along the geometrical dimension will be 7 instead of 100. In case the diagram (or special_selection) is Layer type, no size reallocation is done: the size of diagram using Layer type is often small anyway. In case there is no diagram spatial discretization, nothing happens to the diagram size.

In any case, the diagram will be built only by the molecule respecting the special_selection requirement – and thus the analysis done within FROG are done only to these selected molecules.

Note

For devellopers: the most concrete action of DiagramParameter.special_selection is made in geometry_manager.special_selection_assignement_for_molecules. Use this function to update new option for this attribute.

class Frog.class_DiagramParameter.SingleDiagramParameter(L_input_diagram, GP)[source]¶

Bases: object

This class is defined in order to have the most general option for diagrams already prepared: the name of the diagram, the anaylisis type, how should be performed the discretization and the bin number/dimension.

Here is the list of argument available for the different analysis type:

density: nothing.
molecular_orientation:
proba_style = [string] can be “join” or “independent”. To compute the join or independent distributon respectively. Pay attention when using the join probability: the size can grow very quickly!
hbonds:
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.
rdf:
partner = [string] The moleculartype name of the partner molecule. max_distance = [float] Define the maximal radius for the rdf.
electric_field:
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’.

-alpha, iota, beta, chi:: 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’.

beta, chi:
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.
effective_field:
min_max = [list of two float] The maximal and minimal value to discretize each component of the alpha tensor. 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’. diff_norm = [float] Error maximal allowed which end the self-consistant iteration to solve the molecular effective field matrix. max_iter = [int] The maximal number of allowed iteration to solve the molecular effective field matrix.

property L_reassignation_selection¶

Type [list or bool]

If no special selection is required, this is False

If a special selection is required, this list track the new position of the old bin: it is used to fill the diagram with the new size.

Example: if the original binning is N_bin=10, and after the special selection only the first, 3rd and 8th bin are authorized. This means that the size of the diagram along the spatial direction was orginaly 10, and now it is only 3. In this case, L_reassignation_selection = [0, 3, 1, 3, 3, 3, 3, 2, 3, 3]. There are 3 authorized bin in total (real_space_discretization_bin_number=3), the 1st bin is now the first bin, the 3rd the second and the 8th the third. This reassignation is done in geometry_manager%discretization_space.

add_bin_dimension(new_nbr_bin)[source]¶: Add safely a new dimension to the bin_size.

add_mean_dimension(new_nbr_bin)[source]¶: Add safely a new dimension to the mean_size.

property analysis_type¶

Type [string]

The analysis type of this diagram. Should be in DiagramParameter.L_possible_diagram list.

The analysis type is given by the first argument of the input parameter.

Example

For an input:

['beta', 'Averaged', [1, 100], [-10, 10]]

The sdparameter associated analysis_type is ‘beta’.

property bin_size¶

Type [tuple]

The size of the diagram.value .

The first bin size is relative to the geometrical discretization. If no discretization is performed, bin_size[0] = 1.

The other dimension are given by the user in the rest of the third argument along with the analysis required.

Example

If the input to built the diagram is :

['density', 'Plane_xy', [100]]

The bin size is [100], since only geometrical selection dimension is required for the density analysis.

Example

For an input:

['rdf', 'Plane_xz', [100, 30], 'Methanol_OPLSAA', 10.2]

The bin size is [100, 30]. The 100 refers to the geometrical discretization, and the 30 to the observable discretization – the RDF value for each altitude.

Example

For an input:

['beta', 'Averaged', [1, 100], [-10, 10]]

The bin size is [1, 27, 100]. The 1 refers to the geometrical discretization (none), the 27 to the 27 elements of the beta matrix. For each matrix components, 100 bins are used to discretize the value. Here the independent discribution are computed – i.e. the diagram have not the size 100^27 for obvious reasons…

change_bin_size_value(bin_to_change, value)[source]¶: Change safely the bin_size.

check_format()[source]¶: Check that the format of the SingleDiagramParameter object is conform. Please feel free to add new tests.

property discretization_type¶

Type [integer]

A shortcut for the geometrical discretization used for the diagram. The geometrical discretization is given by the second argument of the input parameter.

user input:

[analysis type, geometrical discretization, [bin number for the geometrical discretization, other bin number], other parameters]

Here are the available geometrical discretization type:

‘Averaged’:

No geometrical discretization. The bin number of the geometrical discretization should be 1.

In this case, discretization_type = -1

‘Plane_ij’:

Where i and j are x, y or z. In this case, the discretization is made over the last axis. If Plane_xy is required, the discretization along the z axis is done. The name of the diagram is updated with ‘slice_z’ in this case – see the name attribute of the SingleDiagramParameter object.

In this case, discretization_type = k where k = 0, 1, 2 for a discretization along the x, y or z laboratory axis.

Layer:

The geometrical discretization is made using the pytim.ITIM module. The number of layer to discretize each interface has to be given using the <bin number for the geometrical discretization>. Note that in the current implementation, Frog support only 2 liquid/gas interfaces.

In this case, discretization_type = 10

Example

For an input:

['rdf', 'Plane_xz', [100, 30], 'Methanol_OPLSAA', 10.2]

The discretization will be made over the y-axis. The bin number to discretize this axis is 100.

For an input:

['density', 'Layer', [4]]

The density discretization is made over 4 layer for each interfaces.

property mean_size¶

Type [tuple or bool]

The size of the diagram.mean .

It is the same size of the bin_size, whithout the last dimension – which is compressed into its average value.

Note

Some analysis have no ‘mean’ value because they are not easely defined – for instance the ‘average value of the RDF. In this case, mean_size = False

property name¶

Type [string]

The name of the diagramm.

The name is composed buy several information. It always start with the analysis type, then the geometrical discretization used. From some analysis, the name can be futher update with other parameter.

name = <analysis_type> + _ + <discretization> + other parameters

See the analysis documentation for more information about how the name of the diagram are created.

Example

If the input to built the diagram is :

['density', 'Plane_xy', [100]]

Then, the name of this diagram will be ‘density_slice_z’.

If no space discretization is required: [’density’, ’All’, [1]], the name is directly ‘density’.

Example

For an input:

['rdf', 'Plane_xz', [100, 30], 'Methanol_OPLSAA', 10.2]

The name will be ‘rdf_slice_y_Methanol_OPLSAA’

Example

For an input:

['beta', 'Averaged', [1, 100], [-10, 10]]

With QM calculation at frequencies:

qmparameter.shg_response = [0.0, 0.05686]

Two diagram will be created with the name ‘beta_0.0’ and ‘beta_0.05686’.

Note

The name of the diagram are fixed by the parameter. Therefore, you should not define several times the set of input parameter, leading to the same diagram name. Frog may crash in unexpected way. If you want to define very similar parameters to compare the resulting diagrams (with the same name), you should run several time Frog several times.

property real_space_discretization_bin_number¶

Type [integer]

If a special condition is requested for the Diagram spatial discretization, real_space_discretization_bin_number is the number of bin that are authorized according to this special condition. Note that the current implementation only work for a Slice spatial discretization.

special_selection_reassignation_list_creation(special_selection)[source]¶

The selection of which molecule should be analyze/add to the diagram is made during the first_part.treat_one_frame function. However, since a smaller part of the box is anaylize, the size of the diagram should be updated accordingly.

This function prepare the list ‘L_reassignation_selection’ in case there is a special selection according to an axis. It will be use later on to built the proper diagram size and axis values.

Frog.class_DiagramParameter.construct_pow_name_unit(name_unit, pow_unit)[source]¶

class Frog.class_DiagramParameter.frog_axis(sdparameter, GP, space=False)[source]¶

Bases: object

How the units are handled by Frog: they are not! During Frog run, the unit are fixed for each quantities. This part of the code us designed to help user to plot/play with the diagrams later on (for instance in jupyter notebooks). This part of the code is still under construction and should be read as a small toolbox. If you wish to use an external library / improve the code go ahead!

contains: value value2 sometimes unit

Frog.class_DiagramParameter.sdparameter_create_axis(sdparameter, GP)[source]¶

Create the axis list related to a Diagram.

The first list is always related to the position of the molecule. For instance the position along the z-axis. The other are related to the analysis performed. For instance the number of H-bonds or the electric field value.

class Frog.class_DiagramParameter.unit(name_analysis, type_object)[source]¶

Bases: object

print_unit()[source]¶

switch_for_given_unit(unit_to_change, new_unit, custom_change, L_unit_understood, L_corresponding_value)[source]¶

switch_unit(unit_to_change, new_unit, custom_change=False, molar_mass=False)[source]¶

7.5. Frog.class_Diagrams module¶

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

Bases: Diagram

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.

static SM_attribute_name(frequency)[source]¶: Define the name of the attribute for a molecule with hold the value relative to this analysis.

classmethod add_single_molecule_property(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype)[source]¶: Read the polarizability from the QM calculation.

add_value_to_diagram(L_box_size, GP, moleculetype, sdparameter, name_attr, kkk)[source]¶: Increament the diagram value with the molecule number ‘’kkk’ value.

end_frame_diagram(L_box_size, sdparameter)[source]¶: Things to do after adding every molecule contribution. For instance renormalization.

classmethod initialize_single_molecule(singlemolecule, mtparameter)[source]¶: Add to the single_molecule object an attribute for the molecular polarizability depending on the type of calculation.

static read_input(L_input_diagram, sdparameter, smparameter)[source]¶: Update the bin_size and the min, max value for every component. The frequency is initialized to the default value.

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

Bases: Diagram

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.

static SM_attribute_name(frequency)[source]¶: Define the name of the attribute for a molecule with hold the value relative to this analysis.

classmethod add_single_molecule_property(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype)[source]¶: Read the hyperpolarizability from the QM calculation.

add_value_to_diagram(L_box_size, GP, moleculetype, sdparameter, name_attr, kkk)[source]¶: Increament the diagram value with the molecule number ‘’kkk’ value.

end_frame_diagram(L_box_size, sdparameter)[source]¶: Things to do after adding every molecule contribution. For instance renormalization.

classmethod initialize_single_molecule(singlemolecule, mtparameter)[source]¶: Add to the single_molecule object an attribute for the molecular hyperpolarizability depending on the type of calculation.

static read_input(L_input_diagram, sdparameter, smparameter)[source]¶: Update the bin_size and the min, max value for every component. The frequency is initialized to the default value.

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

Bases: Diagram

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.

static SM_attribute_name(frequency)[source]¶: Define the name of the attribute for a molecule with hold the value relative to this analysis.

classmethod add_single_molecule_property(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype)[source]¶: Read the hyperpolarizability from the QM calculation or rotate the reference one toward the laboratory frame.

add_value_to_diagram(L_box_size, GP, moleculetype, sdparameter, name_attr, kkk)[source]¶: Increament the diagram value with the molecule number ‘’kkk’ value.

end_frame_diagram(L_box_size, sdparameter)[source]¶: Things to do after adding every molecule contribution. For instance renormalization.

classmethod initialize_single_molecule(singlemolecule, mtparameter)[source]¶: Add to the single_molecule object an attribute for the laboratory hyperpolarizability depending on the type of calculation.

static read_input(L_input_diagram, sdparameter, smparameter)[source]¶: Update the bin_size and the min, max value for every component. The frequency is initialized to the default value.

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

Bases: Diagram

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.

static SM_attribute_name(sdparameter)[source]¶: Define the name of the attribute for a molecule with hold the value relative to this analysis. Here the mean position of the molecule.

classmethod add_single_molecule_property(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype)[source]¶: Should compute the mean position of the molecule according to the function ‘’mean_position’’ defined in the molecule type library file. However, this should have been done before. If this function is called, an error is raised.

add_value_to_diagram(L_box_size, GP, moleculetype, sdparameter, name_attr, kkk)[source]¶: Increament the diagram value with the molecule number ‘’kkk’ value.

end_frame_diagram(L_box_size, sdparameter)[source]¶: Things to do after adding every molecule contribution. For instance renormalization.

classmethod initialize_single_molecule(singlemolecule, mtparameter)[source]¶: Already defined for every molecule: ‘mean_position’ which is a 1x3 array.

static read_input(L_input_diagram, sdparameter, smparameter)[source]¶: Nothing to do, already initialized.

class Frog.class_Diagrams.Dia_effective_field(sdparameter)[source]¶

Bases: Diagram

IMPORTANT NOTE: this part of the code is not working. It is the remaining of previous attends which may or may not be continued later on. This part of the code is not deleted so that future develpment could benefite from the already built structure.

However, if you are the developer which actually work in this area, do not hesitate to start from scratch if you fell that it would be easier.

Compute the effective field coefficient of the molecule type in the molecular frame.

static SM_attribute_name(frequency)[source]¶: Define the name of the attribute for a molecule with hold the value relative to this analysis.

classmethod add_single_molecule_property(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype)[source]¶: TODO

add_value_to_diagram(L_box_size, GP, moleculetype, sdparameter, name_attr, kkk)[source]¶: Increament the diagram value with the molecule number ‘’kkk’ value.

end_frame_diagram(L_box_size, sdparameter)[source]¶: Things to do after adding every molecule contribution. For instance renormalization.

classmethod initialize_single_molecule(singlemolecule, mtparameter)[source]¶: TODO

static read_input(L_input_diagram, sdparameter, smparameter)[source]¶: Update the bin_size and the min, max value for every component. The frequency is initialized to the default value.

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

Bases: Diagram

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.

static SM_attribute_name(sdparameter)[source]¶: Define the name of the attribute for a molecule with hold the value relative to this analysis.

classmethod add_single_molecule_property(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype)[source]¶: Compute the electric field felt by a molecule if required (on_fly). Otherwise, the electric field calculation will be performed when the QM/MM is create, see Prepare_run_QM diagram below.

add_value_to_diagram(L_box_size, GP, moleculetype, sdparameter, name_attr, kkk)[source]¶: Increament the diagram value with the molecule number ‘’kkk’ value.

end_frame_diagram(L_box_size, sdparameter)[source]¶: Things to do after adding every molecule contribution. For instance renormalization.

classmethod initialize_single_molecule(singlemolecule, mtparameter)[source]¶: Add to the single_molecule object an attribute for the electric field depending on the type of electric field calculation.

static read_input(L_input_diagram, sdparameter, smparameter)[source]¶: Update the bin_size and the min, max value for every component.

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

Bases: Diagram

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.

static SM_attribute_name(sdparameter)[source]¶: Define the name of the attribute for a molecule whicth hold the value relative to this analysis. Here the molecular orientation of the molecule.

classmethod add_single_molecule_property(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype)[source]¶: Compute the hbonds between a target molecule and some partner molecules according to the function ‘’compute_hbonds’’ defined in the target or partner molecule type library file.

add_value_to_diagram(L_box_size, GP, moleculetype, sdparameter, name_attr, kkk)[source]¶: Increament the diagram value with the molecule number ‘’kkk’ value.

end_frame_diagram(L_box_size, sdparameter)[source]¶: Things to do after adding every molecule contribution. For instance renormalization.

classmethod initialize_single_molecule(singlemolecule, mtparameter)[source]¶: Seek in the list of asked diagram the ‘hbond’ and add the attribute ‘hbond’ + ‘_’ + ‘ name of the molecule with which the hbond are considerated ‘. For instance, if the hbond between this molecule type and Water or Methanol is asked, the molecule of this molecule type will have the attribute hbond_Water or hbond_Methanol.

static read_input(L_input_diagram, sdparameter, smparameter)[source]¶: Update the SingleDiagramParameter with the informations given by the user. Also check if the compute_hbonds function is defined in this molecular module or in the partner molecular one.

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

Bases: Diagram

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.

static SM_attribute_name(frequency)[source]¶: Define the name of the attribute for a molecule with hold the value relative to this analysis.

classmethod add_single_molecule_property(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype)[source]¶: Read the polarizability from the QM calculation or rotate the reference polarizability toward the laboratory frame.

add_value_to_diagram(L_box_size, GP, moleculetype, sdparameter, name_attr, kkk)[source]¶: Increament the diagram value with the molecule number ‘’kkk’ value.

end_frame_diagram(L_box_size, sdparameter)[source]¶: Things to do after adding every molecule contribution. For instance renormalization.

classmethod initialize_single_molecule(singlemolecule, mtparameter)[source]¶: Add to the single_molecule object an attribute for the laboratory polarizability depending on the type of calculation.

static read_input(L_input_diagram, sdparameter, smparameter)[source]¶: Update the bin_size and the min, max value for every component. The frequency is initialized to the default value.

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

Bases: Diagram

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.

static SM_attribute_name(sdparameter)[source]¶: Define the name of the attribute for a molecule with hold the value relative to this analysis. Here the molecular orientation of the molecule.

classmethod add_single_molecule_property(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype)[source]¶: Compute the molecular orientation of the molecule according to the function ‘’compute_molecular_orientation’’ defined in the molecule type library file.

add_value_to_diagram(L_box_size, GP, moleculetype, sdparameter, name_attr, kkk)[source]¶: Increament the diagram value with the molecule number ‘’kkk’ value.

end_frame_diagram(L_box_size, sdparameter)[source]¶: Things to do after adding every molecule contribution. For instance renormalization.

classmethod initialize_single_molecule(singlemolecule, mtparameter)[source]¶

static read_input(L_input_diagram, sdparameter, smparameter)[source]¶: Redefine the bin_size according to the number of value needed to describe the molecular orientation of this molecular type. Please, note that if a Plane discretization have been required, the bin number related has been already removed in sdparameter.__init__ .

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

Bases: Diagram

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.

static SM_attribute_name(sdparameter)[source]¶: Define the name of the attribute for a molecule with hold the value relative to this analysis.

classmethod add_single_molecule_property(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype)[source]¶: Compute the distance between the target molecule and the partner molecules in the target molecule neighbourhood.

add_value_to_diagram(L_box_size, GP, moleculetype, sdparameter, name_attr, kkk)[source]¶: Increament the diagram value with the molecule number ‘’kkk’ value.

end_frame_diagram(L_box_size, sdparameter)[source]¶: Things to do after adding every molecule contribution. For instance renormalization.

classmethod initialize_single_molecule(singlemolecule, mtparameter)[source]¶: Seek in the list of asked diagram the ‘rdf’ and add the attribute ‘hbond’ + ‘_’ + < name of the molecule with which the rdf are considerated >. For instance, if the rdf between this molecule type and Water, and Methanol is asked, the molecule of this molecule type will have the attribute rdf_Water and rdf_Methanol.

static read_input(L_input_diagram, sdparameter, smparameter)[source]¶: Update the bin_size and save the input.

class Frog.class_Diagrams.Diagram(sdparameter)[source]¶

Bases: object

static add_empty_diagram(sdparameter)[source]¶: Creat a diagram of the specified type. Every diagram are the same (with respect to their attribues, e.g. value or population) but have different method associated. That is why the type of the diagram matters.

add_population()[source]¶: Add a population to the diagram.

add_value_to_diagram(position)[source]¶: Add an occurence to the diagram. The position argument MUST BE a tuple.

add_value_to_mean(sdparameter, bin_space, value)[source]¶: Add a population to the diagram.

property axis_observable¶

Type [frog_axis]

The x-axis of the discretize observable. You can use this axis to plot the distrubiton ‘value’ along the observable direction. See the class frog_axis for more information. ADD REF.

Example

To plot the (normalized) distribution of an observable for a given geometrical selection bin (here the 0th):

plt.plot(my_diagram.axis_observable.value, my_diagram.value[0]/my_diagram.population)

More examples can be found HERE.

property axis_population¶

Type [list of int]

If space discretization is required and the mean value is computed, the number of molecule involve in each geometrical bin is tracked here.

Example

If the slice_ij argument is used to discretize the result along a given laboratory axis, the axis_population will be an array of the size of the number of bin used to discretize this axis. It will contains the number of molecule that participated to the diagram for every slice. If you plot the axis_population you have something proportional to the density along the discretized axis.

property axis_space¶

Type [frog_axis]

The x-axis of the space selection. If no space selection is performed, this axis is useless. If you performed axis discretization, it will contains the position of the slices along the chosen axis. You can use this axis to plot the distrubiton ‘value’ along the geometrical discretization, or perform 2D plot along with the axis_observable axis. See the class frog_axis for more information. ADD REF.

Example

To plot the mean value along the spacial discretization:

plt.errorbar(my_diagram.axis_space.value, my_diagram.mean, yerr=my_diagram.sd)

More examples can be found HERE.

end_diagram(sdparameter, GP)[source]¶: Normalize the average and the standard deviation according to the total population number. Creates the axis for the diagram. This is done here so that the other temporary diagram are lighter.

end_frame_diagram()[source]¶: Compute the valuesquare. Should be called at the end of a frame.

property mean¶

Type [float or list of float]

For all the analysis type except the ‘density’ and the ‘rdf’ (for Radial Distribution Function), mean value and standard deviation are already available in the diagram object using the attribute mean and sd.

The size of the mean and sd depend on the analysis performed. If space discretization is required, the mean and sd are computed with respect to the same geometrical selection.

Example

The input used to generate the diagram is [‘molecular_orientation’, ‘Plane_xy’, [100, 100], ‘independent’]. The size of the value distribution is 100 X 3 X 100. The first 100 bin refers to the geometrical selection (along the z-axis of the laboratory frame), while the other 100 bin refers to the discretization of the molecular orientation of the molecule. In this case, the mean attribute size will be 100 x 3. For every z-slice, the mean value for the 3 independent orientation are computed for every molecule found within these slices.

Note

If no space discretisation is required, the number of

merge_diagram(otherself)[source]¶: Merge the result of different frame – or more generally different diagram object. No normalization should be perfromed at this point.

property name¶

Type [string]

The diagram name. Defined by the analysis it refers to, along with the discretization parameters and sometimes some parameters of the analysis.

Example

If the analysis required is the ‘molecular orientation’ and the space-discreatization is made over the position of the molecule with respect to the laboratory z-axis, the name of the diagram will be molecular_orientation_slice_z.

property population¶

Type [integer]

The total number of molecule that participate to this diagram. For the case where no geometrical discretization is performed, it is just (Number of molecule) X (Number of time). For the other geormetrical selection it can become more structure-dependent and time-dependent.

property sd¶

Type [float or list of float]

The standard deviation relative to the mean value of the ‘mean’ attribute. The size of the sd is the same as the mean.

sd = sqrt[mean(value**2) - mean**2]

If you are using time-uncorrelated frame, you may decrease this standard deviation:

sd = sd/sqrt(Number time step)

Or even more if you can define space-uncorrelation.

property size¶

Type [tuple]

The size of the distribution. The first element is the space discretization, the other refers to the observable discretization – and depends on the analysis performed.

switch_unit_diagram(what_to_change, unit_to_change, new_unit, custom_change=False, molar_mass=False)[source]¶: Switch the unit of the diagram axis, not diagram.value, diagram.valuesquare or the mean and sd!!!

property unit¶

Type [unit]

The unit of the observable, depends on the analysis performed. See the class unit for more information. ADD REF

property value¶

Type [numpy array]

The distribution of the observable across the geometrical selection. The size of the array is given by the size attribute. It is an non-normalized distribution: it contains only the number of molecule found to have the observable value in a given range. The normalization is up to the user. If you want to perform the normalization with respect to the total number of molecule which participated to this distribution, use the attribute population. If some geometrical selection is used (for instance along a laboratory axis), one can use the axis_population attribute to normalized the space-discretize distribution with respect to the number of molecule which participated to the distribution for every space-bin. See axis_population attribute for more details.

Example

For a density analysis along the z laboratory axis with a number of bin 100 ( input parameter: [‘density’, ‘Plane_xy’, [100]). The my_diagram.value attribute is a list of size 100 – given also by my_diagram.size. The mean position of the water molecule are computed for every frame, and the position along the z laboratory axis is discretize into 100 bin with respect to the box size in the z direction. Let’s say, the box size along the z direction is 150 A. Therefore, a molecule with mean position along the z axis 74 A corresponds to the 50th bin. Thus, for every molecule with a z mean position of 74 A, $\texttt{FROG}$ adds 1 in the 50th bin of my_diagram.value – i.e. my_diagram.value[49] since python list index starts from 0.

Another example more complex using the molecular orientation. In this case, the input used to generate the diagram is [‘molecular_orientation’, ‘Plane_xy’, [100, 100], ‘independent’] in the input file. For a given molecule, Frog will perform two discretization: one regarding the mean position (like the previous case) and one regarding the molecular orientation. Let’s say the mean position of the molecule in the z laboratory axis is 89 A and the molecular orientation is [-0.89, 0.1, 0.42]. As for the above example, the space discretization uses 100 bin. The mean position 89 A correspond to the 60th bin. In order to discretize the molecular orientation (the observable), 100 bin is also used. The molecular orientation range from -1 to 1 (projections). Therefore, a molecular orientation of [-0.89, 0.1, 0.42] correspond to the bin 6, 56 and 72. Since the independent distribution is required here, the my_diagram.value will be a 100X3X100 array – given also by my_diagram.size. If Frog found a molecule with a z laboratory axis mean position of 89 A and a molecular orientation of [-0.89, 0.1, 0.42], it will add 1 to the elements:my_diagram.value[59][0][5], my_diagram.value[59][1][55] and my_diagram.value[59][2][71].

Note: If the join distribution was asked, the my_diagram.value will be a 100X100X100X100 array – given also by my_diagram.size. In this case, the molecule would lead to only one element update: my_diagram.value[59][5][55][71].

property valuesquare¶

Type [numpy array]

At the end of a frame analysis, the attribute ‘value’ at the power 2 is stored in the attribute ‘valuesquare’. When merging the results of all the time step treated, the ‘value’ and ‘valuesquare’ of every diagram are summed respectively. This attribute can be used to compute the standard deviation later on for the distribution.

Note

It is assumed that the observable are correlated for a given frame. See HERE for more details.

class Frog.class_Diagrams.Prepare_run_QM(sdparameter)[source]¶

Bases: Diagram

This Diagram class is not doing any analysis but preparing the scripts for a Dalton run. It is called whenever any ‘’optical’’ analysis requiering an QM calculation is needed. This class will prepare the electrostatic environment if required.

static SM_attribute_name(sdparameter)[source]¶: Define the name of the attribute for a molecule with hold the value relative to this analysis.

classmethod add_single_molecule_property(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype)[source]¶: Check if a QM run should be perform for this molecule. If so, write the .dal, .mol and .pot file. Save also the rotational matrix (to go from the molecular to the laboratory frame).

classmethod initialize_single_molecule(singlemolecule, mtparameter)[source]¶: Initialize boolean to follow if the QM run of this molecule should be done (IS_QM_run). Set to ‘TODO’ if the QM calculation should be done. Set to ‘DONE’ if the QM calculation have been done.

Frog.class_Diagrams.str_to_class(classname)[source]¶: Return a class knowing the classname.

7.6. Frog.class_Molecule module¶

class Frog.class_Molecule.MoleculeType(GP, molecule_type_name, where_are_molecules)[source]¶

Bases: object

property L_key_mol¶

Type [list of integer]

A list where every integer is the tag of a molecule of this Molecule Type. For instance, L_key_mol = [1, 2, 3] means that in the topology file, the molecule number 1, 2 and 3 are of this molecule type.

property L_key_selection_traj¶

Type [integer, integer]

The first and the last atom (labelling from the topology file) of the molecule type ensemble.

property L_molecule¶

Type [list of SingleMolecule]

A list of every molecule of this MT for a given time step. These object contains all the molecular properties computed by the software. For instance the molecule’s position, orientation, beta… See the SingleMolecule object.

Note

If you want to perform by yourself extra post-analysis, you may want to use this list. You can acces every molecule using myMT.L_molecule[molecule_number].whatever_individual_property. For instance, myMT.L_molecule[100].electric_field_PE to acces the electric field felt by the 101th molecule of this MT at this time step.

add_empty_diagram()[source]¶: Add for every analysis to do a diagram with the proper name in the MoleculeType (MT) object.

add_empty_molecule(GP)[source]¶: Add a list of empty molecule in the MoleculeType (MT) object. Each molecule have the attribute needed to store the required analysis.

check_molecule_basics(GP)[source]¶: Check if the molecule provided in the input file are found in the MD trajectory with the good geometry.

check_pe_environement(GP)[source]¶: TODO

check_polarizable_description(GP)[source]¶: Check that this molecule type has a backup description of its polarizability. It will first check on the optical parameter, then on the molecular module.

check_qm_target(GP)[source]¶: TODO

end_diagram(GP)[source]¶: Conclude the FROG run for the diagram. Today we call just one function but if one wants to perform more analysis once all of the diagram are done here would be a nice localisation (for instance correlation analysis).

end_initialize(GP)[source]¶: Check if the analysis required can be run. Change the name of the ‘’optical’’ diagram in case they are extracted from a response calculation at a given frequency.

initialize_empty_for_frame(GP)[source]¶: Provide the final MoleculeType (MT) object ready for a frame analysis. Initialize the diagrams and the singlemolecule object.

input_section_check_update(input_number=-1, for_check=False)[source]¶: Check that the previous input function has been called and update the safety-argument for this one.

property input_section_checks¶

Type [list of bools]

Safety-intended input. This list contains booleans set to False. The number of booleans corresponds to the number of function to be called in the input section. Currenty:

read_diagram_input

read_optic_properties_input

end_initialize

If these function are called, they set there boolean to True After reading the input, Frog checks that the input_section_checks of every MT contains only True.

merge_frame(otherself)[source]¶: TODO

property mtparameter¶

Type [MoleculeTypeParameter]

The object containing the properties of this molecule type: what analysis should be perform with this molecule type as well as usefull information regarding the expected caracteristics of this molecule type. See the other object involves like SingleMoleculeParameter, DiagramParameter or OpticalParameter.

property name¶

Type [string]

Name of the molecule type given when creating the instance (molecule_type_name argument). It is very important that this name refer to a molecule module defined in the frog library - for exemple, WaterTIP4P with the module WaterTIP4P.py. The name can be completly different from the one used during the MD simulation.

Note

Defined directly by the user when creating a new Molecule Type object. The name is the second input parameter

property population¶

Type [integer]

Number of molecule of this type.

Warning

The number of molecule and the topology shall not change during the MD.

read_diagram_input(GP, L_diagram_analysis_to_perform, special_selection=False)[source]¶: This function was made to make the user input simplier.

read_optic_properties_input(GP, alpha_calculation_style=False, L_alpha_ref=False, beta_calculation_style=False, L_beta_ref=False, beta_order='dipole', effective_field_on_beta=False, efparameter=False, effective_field_distance_neigh=False, where_to_run_QM=False, qmparameter=False, selection_tool=False)[source]¶

Defines the Optical Parameter of this MT.

One input is mandatory: the GlobalParameter (GP) of the run as first argument.

The other arguments are optional in the sens that they have a default value is not given by the user. See the Optical Parameter attribute for more information about them.

Example

A good habit can be to first defines the attributes value in your input file, and then to pass them to this function:

alpha_calculation_style = 'Fixed for all'
L_alpha_ref = np.array([[9.8, 0, 0], [0, 9.8, 0], [0, 0, 9.8]])
myMT.read_optic_properties_input(GP, alpha_calculation_style=alpha_calculation_style, L_alpha_ref=L_alpha_ref)

Warning

Today, the attributes effective_field_on_beta, efparameter and effective_field_distance_neigh SHALL NOT be used. They were designed for effective field calculation, which is not yet complete in Frog.

Note

This function was made to make the user input simplier, right?

Note

In the rest of the documentation, this function call is often written as read_optic_properties_input(…, the_argument=value, …). In any case, you should defines always the GP first, and all the other attribute you need in only one call. If you are not using an attribute, just do not define it or set its value to the default one.

property where_are_molecules¶

Type [string or list]

Defined what molecule of the MD are considerated as a molecule of this type. 2 way of defining this is defined:

‘all’: to assign all the molecule available in the MD to this Molecule Type.
A list of the first and the last molecule number. It is very important to note that only concecutivelly labelled molecule can be assign to be part of the same molecule type.
Example: [1, 1700] to assign from the 1st molecule to the 1700th molecule, including the 1700th molecule.

Note

Defined directly by the user when creating a new Molecule Type object. where_are_molecules is the third input parameter

class Frog.class_Molecule.MoleculeTypeParameter[source]¶

Bases: object

property dparameter¶

Type [DiagramParameter]

Contains the DiagramParameter of this MT. See The DiagramParameter object for more information.

property optparameter¶

Type [OpticalParameter]

Contains the OpticalParameter of this MT. See The OpticalParameter object for more information.

property smparameter¶

Type [SingleMoleculeParameter]

Contains the SingleMoleculeParameter of this MT. See The SingleMoleculeParameter object for more information.

class Frog.class_Molecule.SingleMolecule(GP, mtparameter)[source]¶

Bases: object

compute_mean_position(kkk, u, ts, molecule_type_module, smparameter, L_box_size)[source]¶: Compute the mean position of the molecule using the function defined in the molecule type library file.

compute_rot_matrix(kkk, u, ts, molecule_type_module, smparameter, L_box_size)[source]¶: compute the rotational matrix

print_typical_position(MT_name, filename)[source]¶: when the trajectory is not available print the typical position of this molecule in XYZ format from the mean position and the rotational matrix of this single molecule and the typical geometry of the molecule type

7.7. Frog.class_OpticalParameter module¶

class Frog.class_OpticalParameter.EFParameter[source]¶

Bases: object

NOT USED IN THE CURRENT IMPLEMENTATION

Contains all the information to perform efective field (EF) calculation for this molecule type. This class have been defined in order to store the parameter of the effective field calcualtion at one place.

Variable defined by the user:

max_iteration: [integer] Set the maximal number of iteration authorized for the self-consistancy part of the effective field calculation. Note that this parameter is global for all the molecule type and should be defined only once.

max_diff_norm: [float] Set the maximal relative evolution of the effective field matrix under which the self consistancy run is considerated converged. Note that this parameter is global for all the molecule type and should be defined only once.

frequency = [list or string] The frequency at which the effective calculation should be performed. Note that the default value is ‘REF’, meaning that a zero frequency.

max_distance_neigh = [float] The maximal distance to consider a neighbourg in a molecule environment for the effective field. Note that this value can depend on the molecule type. Setting this value to 0 will set the effective field of this molecule to unity. You may not initialized this value: in this case the value will be taken from the GP – equal to the maximal distance set by at least one of the molecule type.

check_input(optparameter, GP)[source]¶: Check the effective field parameters and update some value to GP

class Frog.class_OpticalParameter.ElectrostaticDescription[source]¶

Bases: object

Property define by reading the molecular type module of each MT.

Each molecule is decomposed into elementary charge, dipole, qudrupole or site to be polarized. These sites are them sorted into several list contained in this object and built while constructing the neighborhood. Once all the neighbors found, these sites are saved into the .pot file in the Dalton-frendly format so that it can be used during the QM/MM calculation.

Note that this object is also used to compute the electrostatic field felt by a molecule.

property L_charge_order_0¶

Type [list or str]

If defined to a list, means that some site defined in L_localization_site are associated to a point charge. In this case, L_charge_order_0 defines the site number and the charge of every point charge.

Example

L_charge_order_0 = [[2, -1.1128], [3, 0.5564], [4, 0.5564]]

3 point charge are defined. The first point charge is negativly charged, q=-1.1128 e, and is located at the 2nd element of L_localization_site. The 2nd and 3rd point charge are positivly charged, q=0.5564 e, and are located at the 3rd and 4th element of the L_localization_site. Here, the first element of L_localization_site has no point charge attached.

Note

The assignement of the charge with the site location starts at 1 instead of 0.

L_charge_order_0 = [[1, q1], [2, q2]…]

Assigns to the first site of L_localization_site the charge q1, to the 2th site the charge q2 ect…

property L_charge_order_1¶

Type [list or str]

If defined to a list, means that some site defined in L_localization_site are associated to a dipole moment. In this case, L_charge_order_1 defines the site number and the dipole vector.

Example

L_charge_order_1 = [[1, [-0.25, -0.25, -0.25]]]

1 dipole is defined at the position L_localization_site[0] with a dipole moment [-0.25, -0.25, -0.25] in a.u. .

Note

The assignement of the dipole with the site location starts at 1 instead of 0.

L_charge_order_1 = [[1, vec1], [2, vec2]…]

Assigns to the first site of L_localization_site the dipole moment vec1, to the 2th site the dipole moment vec2 ect…

property L_charge_order_2¶

Type [list or str]

If defined to a list, means that some site defined in L_localization_site are associated to a quadrupole moment. In this case, L_charge_order_2 defines the site number and the quadrupole value. The quadrupole have to be symetric: they are define only by the [xx xy xz yy yz zz] values.

Example

L_charge_order_2 = [[1, [-0.25, -0.25, -0.25, -0.25, -0.25, -0.25]]]

1 quadrupole is defined at the position L_localization_site[0] with a quadrupole value moment [xx xy xz yy yz zz] = [-0.25, -0.25, -0.25, -0.25, -0.25, -0.25] in a.u. .

Note

The assignement of the quadrupole with the site location starts at 1 instead of 0.

L_charge_order_2 = [[1, qua1], [2, qua2]…]

Assigns to the first site of L_localization_site the quadrupole qua1, to the 2th site the quadrupole qua2 ect…

property L_localization_site¶

Type [list or str]

The space-position of every site needed for the electrostatic description of the molecule. These positions will be used later on by the L_charge_order_0, L_charge_order_1, L_charge_order_2 and L_polarization_order_1_1 attribute. Note that these position are given in the same referential as the molecule position. There are as many element in this list as ‘site’. However, each ‘site’ can have only point charge value, and or dipole, and or quadrupole moments, or nothing.

Note

At the initialization, L_localization_site = ‘NotProvided’. If you do not want to assign any electrostatic description to a molecule type, just do not update any value in the electrostatic_description molecular module function. If L_localization_site = ‘NotProvided’, Frog will considere this as an empty electrostatic description an will pass this molecule when building the electrostatic environment.

However, this way the molecule will not be printed if an .xyz file is generated to keep a track of every configuration. Thus, if you want that a MT has no impact in an electrostatic scheme, but you still want to have it printed in the .xyz file, you can define the L_localization_site attribute, the L_localization_type, an nothing more.

property L_localization_type¶

Type [list or str]

The list of the site name associated to each localization site. The length of L_localization_site and L_localization_type should be the same. The name attributed to each site are arbitrary and have no incidence on the QM calculation. They are used if the .xyz electrostatic environment should be printed.

property L_polarization_exclude¶

Type [list or str]

Defines for some dipole a list of dipole from which they cannot be polarized.

Example

L_polarization_exclude = [[1, [2, 3, 4]]]

The dipole located at the site 1 (position L_localization_site[0]) cannot be polarized by the dipole localted at the site 2, 3 and 4.

Note

The assignement of this list with the site location starts at 1 instead of 0, as the similar attribute of the Electrostatic Description object.

Note

This behavior has not been extensively tested, please read the relative part on the Dalton manual (polarizable electrostatic emmebedding, and the exclude partern).

property L_polarization_order_1_1¶

Type [list or str]

If defined to a list, means that some site defined in L_localization_site are associated to a polarizable dipole. In this case, L_polarization_order_1_1 defines the site number and the polarizability of these site. The polarizability have to be symetric: they are define only by the [xx xy xz yy yz zz] values.

Example

L_polarization_order_1_1 = [[1, [-0.25, -0.25, -0.25, -0.25, -0.25, -0.25]]]

1 polarizable site is defined at the position L_localization_site[0] with a polarizability [xx xy xz yy yz zz] = [-0.25, -0.25, -0.25, -0.25, -0.25, -0.25] in a.u. . It means that a dipole moment can be created at the first site location by the neighborhood using this polarizability value.

Note

The assignement of the polarizability with the site location starts at 1 instead of 0.

L_charge_order_2 = [[1, alpha1], [2, alpha2]…]

Assigns to the first site of L_localization_site the polarizability alpha1, to the 2th site the polarizability alpha2 ect…

merge_mol(otherself)[source]¶: Merge the electrostatic description of otherself with self. First update the maximal multipole order and polarizable order and then merge the list of charge/dipole/quadrupole/polarizability description.

property multipole_order¶

Type [int]

The maximal order of charge distribution description used in this ElectrostaticDescription object.

If multipole_order=0, only point charge are used. If multipole_order=1 dipole are also used. If multipole_order=2, quadrupolar moment are also used.

This attribute is used to keep track of the maximal multipole order to make esier the writting of the dalton potential input file.

property polarization_order¶

Type [int]

The maximal order of polarizability used in this ElectrostaticDescription object.

If multipole_order=0, no polarizable molecule are defined. If multipole_order=1 some molecule are polarizable..

This attribute is used to keep track of polarizability to make esier the writting of the dalton potential input file.

Note

This attribute is not directly related to the QMParameter.pe_order used. It refers to the polarizability of the neighborhood. If the electrostatic scheme used allows to use polarizability but no molecule are polarizable according to their MT electrostatic description, then the result will be same as if QMParameter.pe_order=0 is used.

rescale_values(rescaling_charges)[source]¶

class Frog.class_OpticalParameter.OpticalParameter[source]¶

Bases: object

property IS_run_QM¶

Type [bool]

True if there are QM calculation to perform, False otherwise.

Not user defined

Note

Instead we can use the qmparameter to know if there is QM calculation or not for this optparameter. But we felt that it would be more readable/understanable this way.

property L_QM_todo¶

Type [bool or list]

The list of the localisation of the QM calculation to perform for this MT at this time step. This list is built after the first part and is used as a starting point during the second part to built all the QM calculation to do.

You can check by opening this list at a given time step that the dalton files are indeed written in the directories and that the molecule respect the OpticalParameter.where_to_run_QM and OpticalParameter.selection_tool requirements.

If no QM calculation should be done for this MT, OpticalParameter.L_QM_todo is set to False. If there can be QM calculation but none have to be done (because the QM calculation have aloready been performed or if no molecule respect both OpticalParameter.where_to_run_QM and OpticalParameter.selection_tool requirements) for this time step, OpticalParameter.L_QM_todo = []

Not user defined

property L_alpha_ref¶

Type [bool or list]

If the OpticalParameter.alpha_calculation_style=’Fixed for all’, the OpticalParameter.L_alpha_ref has to be set to a 3x3 list. This value is used to defined the polarizability of every molecule of this MT in their molecular frame.

If OpticalParameter.alpha_calculation_style is set to any other value, OpticalParameter.L_alpha_ref should be False, its default value.

Example

In your input parameter file, declare the OpticalParameter.L_alpha_ref value using:

myMT.read_optic_properties_input(GP, ...,  L_alpha_ref=your_value, ...)

where the ‘…’ stands for the other parameter you may need to use.

Note

The unit to declare the polarizability should be atomic unit. For instance, the polarizability of water at optical freuqnecy is around: L_alpha_ref = [[9.8, 0, 0,], [0, 9.8, 0], [0, 0, 9.8]].

property L_beta_ref¶

Type [bool or list]

If the OpticalParameter.beta_calculation_style=’Fixed for all’, the OpticalParameter.L_beta_ref has to be set to a 3x3x3 list. This value is used to defined the hyperpolarizability of every molecule of this MT in their molecular frame.

If OpticalParameter.alpha_calculation_style is set to any other value, OpticalParameter.L_beta_ref should be False, its default value.

Example

In your input parameter file, declare the OpticalParameter.L_beta_ref value using:

myMT.read_optic_properties_input(GP, ...,  L_beta_ref=your_value, ...)

where the ‘…’ stands for the other parameter you may need to use.

Note

The unit to declare the hyperpolarizability should be atomic unit. For instance, the hyperpolarizability of water in vacuum at the DFT/CAMB3LYP level with basis d-aug-cpVTZ at 800~nm is: L_beta_ref = [[[0, 0, -12.4,], [0, 0, 0], [-12.4, 0, 0]], [[0, 0, 0,], [0, 0, -7.4], [0, -7.4, 0]], [[-12.5, 0, 0,], [0, -5.0, 0], [0, 0, -15.3]].

property L_molecule_tracked¶

Type [bool or list]

Contained the list of the autorised molecule by the OpticalParameter.selection_tool attribute.

Note user defined.

property alpha_calculation_style¶

Type [bool or str]

If no analysis (i.e. diagram) declared are of type alpha or iota, the alpha_calculation_style have to be False, default value. Otherwise the run will crash. In the same way, if you have declared an alpha or iota analysis, you have to set alpha_calculation_style to one of the possible value:

‘Fixed for all’:

The alpha tensor is given by the attribute OpticalParameter.L_alpha_ref . In this case, the polarizability in the molecular frame is fixed and equal to this value. The polarizability in the laboratory frame is given by the molecule orientation: it is a product of this OpticalParameter.L_alpha_ref with the SingleMolecule.rot_mat using the function: L_iota = Frog.toolbox.rotate_2nd_order_tensor(SingleMolecule.rot_mat.T, OpticalParameter.L_alpha_ref). Note that the rotational matrix, SingleMolecule.rot_mat is given by the molecular library file function Frog.Molecules.my_MT.compute_rotational_matrix .

‘QM’:

The polarizability is computed for each molecule selected, see the OpticalParameter.where_to_run_QM and OpticalParameter.selection_tool attributes, at the QM level. The polarizablity is computed using the parameters provided in the OpticalParameter.qmparameter object. For a single molecule, the polarizability in the laboratory frame is computed (iota), and the alpha is obtained using the molecule orientation: L_alpha = toolbox.rotate_2nd_order_tensor(SingleMolecule.rot_mat, L_iota) .

Example

In your input parameter file, declare the OpticalParameter.alpha_calculation_style value using:

myMT.read_optic_properties_input(GP, ...,  alpha_calculation_style=your_value, ...)

where the ‘…’ stands for the other parameter you may need to use.

Note

No ‘iota_calculation_style’ has been defined since the alpha and iota are related by the molecule orientation.

property beta_calculation_style¶

Type [bool or str]

If no analysis (i.e. diagram) declared are of type beta or chi, the beta_calculation_style have to be False, default value. Otherwise the run will crash. In the same way, if you have declared a beta or chi analysis, you have to set beta_calculation_style to one of the possible value:

‘Fixed for all’:

The beta tensor is given by the attribute OpticalParameter.L_beta_ref . In this case, the hyperpolarizability in the molecular frame is fixed and equal to this value. The hyperpolarizability in the laboratory frame is given by the molecule orientation: it is a product of this OpticalParameter.L_beta_ref with the SingleMolecule.rot_mat using the function: L_chi = Frog.toolbox.rotate_3rd_order_tensor(SingleMolecule.rot_mat.T, OpticalParameter.L_beta_ref). Note that the rotational matrix, SingleMolecule.rot_mat is given by the molecular library file function Frog.Molecules.my_MT.compute_rotational_matrix .

‘QM’:

The hyperpolarizability is computed for each molecule selected, see the OpticalParameter.where_to_run_QM and OpticalParameter.selection_tool attributes, at the QM level. The hyperpolarizablity is computed using the parameters provided in the OpticalParameter.qmparameter object. For a single molecule, the hyperpolarizability in the laboratory frame is computed (chi), and the beta is obtained using the molecule orientation: L_beta = toolbox.rotate_3rd_order_tensor(SingleMolecule.rot_mat, L_chi) .

Example

In your input parameter file, declare the OpticalParameter.beta_calculation_style value using:

myMT.read_optic_properties_input(GP, ...,  beta_calculation_style=your_value, ...)

where the ‘…’ stands for the other parameter you may need to use.

Note

No ‘chi_calculation_style’ has been defined since the beta and chi are related by the molecule orientation.

property beta_order¶

Type [str]

Warning

ONLY FOR beta_calculation_style = ‘QM’

Define at which order you want to compute the first hyperpolarizability:

‘dipole’:

Default value. Compute the first dipole-dipole hyperpolarizability. In other words: the induced dipole moment at frequency 2w through dipolar interaction with electromagnetic field at frequency w. (<<mu; mu, mu>>)

‘quadrupole’:

Compute the first dipole-dipole hyperpolarizability and the quadrupole-dipole interaction. This will update the beta and chi diagram type name. For every diagram, 3 diagram are created: one with the original name (for instance beta_0.0056) which will contain the dipole-dipole first hyperpolarizability. Another with the induced dipole moment with a dipole and quadrupole interaction (<<mu; mu, Q>>). The name of this diagram is update using ‘dq’ for dipole-quadrupole. Finally, a last diagram is created for the quadrupole induced by dipole interaction (<<Q; mu, mu>>). The name of this diagram is update using ‘qd’ for dipole-quadrupole.

The size of the dq and qd diagram is 3x3x3x3. The component ijkl is encoded in the diagram using 81 component: i*27+j*9+k*3+l.

Note

For the frequency symmetry and the convention, please read the documentation about the hyperpolarizability, ADD REF.

Example

In your input parameter file, declare the OpticalParameter.beta_order value using:

myMT.read_optic_properties_input(GP, ...,  beta_order=your_value, ...)

where the ‘…’ stands for the other parameter you may need to use.

Note

No ‘chi_order’ has been defined since the beta and chi are related by the molecule orientation.

property compute_electric_field_PE¶

Type [bool]

Set to True of there are diagrams defined which track the electrostatic field generated by the environment during the QM calculation. Originaly related to the option ‘PE’ of an electric_field analysis.

If set to False, default, the electric field generated by the environement for each configuration is not computed by Frog nor store. But Dalton will still do it during the QM calculation.

Not user defined

property pe_level¶

Type [int]

The maximal PE level used for this MT. It should be the same as the one defined in the OpticalParameter.qmparameter in many cases.

If no electrostatic environement have to be built, default value, OpticalParameter.pe_level = -1.

Not user defined

property qmparameter¶

Type [bool or QMParameter]

The QMParameter for this MT. This attribute has to be defined if one optical analysis required QM calculation. If no QM calculation is needed for this MT, should be set to False. See the part relating to this QMParameter class for more information about it.

Example

To set the QMParameter, initialize it first, then fill the required attribute. Enventualy set it to the OpticalProperty using the usual read_optic_properties_input function:

qmparameter = QMParameter() # empty object
qmparameter.calculation_style = 'PE' # example of attribute
qmparameter.theory_lv = 'DFT' # example of attribute
myMT.read_optic_properties_input(GP, ...,  qmparameter=qmparameter, ...) # set it to the optparameter

read_optic_properties_input(GP, alpha_calculation_style, L_alpha_ref, beta_calculation_style, L_beta_ref, beta_order, effective_field_on_beta, efparameter, where_to_run_QM, qmparameter, selection_tool)[source]¶

Initialized the optical properties, including QM runs

Short overlook at the possible input: - alpha_calculation_style: Can be: False, ‘Fixed for all’ or ‘QM’. False by default. - L_alpha_ref: Can be False or a 3x3 list. False by default. - beta_calculation_style: Can be: False, ‘Fixed for all’ or ‘QM’ . False by default. - L_beta_ref: Can be False or a 3x3x3 list. False by default. - beta_order: can be: ‘dipole’ or ‘quadrupole’. ‘dipole’ by default - effective_field_on_beta: Can be: False or True. False by default. - effective_field_frequency: Can be list or False. False by default. - effective_field_distance_neigh: Can be float or False. False by default. - where_to_run_QM: Can be: False or a list. False by default. - qmparameter: Can be: False or an qmparamter object. False by default. - selection_tool: Can be: False or ‘traking_molecules’. False by default.

property selection_tool¶

Type [bool or list or str]

Defines another way of selecting the molecule of this MT which should be QM-treated. This method are very different from the one proposed in OpticalParameter.where_to_run_QM: they are not based on laboratory-based geometrical selection. Both selection, OpticalParameter.where_to_run_QM and OpticalParameter.selection_tool, can be used simultaneously to minimize the QM calculation time.

Today, the option available in this attribute is small, but if you want to implement easy-to-use selection for the QM calculation, you may want to define them here.

Possible value for OpticalParameter.selection_tool:

False:

Default value, no extra selection is defined using this attribute.

In this case, the OpticalParameter.selection_tool is set to False.

[‘traking_molecules’, list of the molecule]:

Only the molecule with there molecule number in the list provided as second argument are QM-treated. Note that the labbeling is the same as the one given in MoleculeType.where_are_molecules: it refers to the MD topology labelling.

In this case, the pticalParameter.selection_tool is set to ‘traking_molecules’. The list of the authorised molecule os stored in OpticalParameter.L_molecule_tracked.

Example

traking_molecules = ['traking_molecules', [1005, 1050]]
myMT.read_optic_properties_input(GP, ...,  traking_molecules=traking_molecules, ...)

where the ‘…’ stands for the other parameter you may need to use. In this case, only the molecule numbered 1005 and 1050 can be QM-treated for all the time step. It is not the 1005th and 1050th molecule of the MT, but the 1005th and 1050th molecule of the MD labbeling – except when you have only one MT where the 2 labbeling are the same or if it is the first MT declared.

Note

For develloper: the concrete action of OpticalParameter.selection_tool is made in geometry_manager.optparameter_selection_tool_molecule. Use this function to update new option for this attribute.

property where_to_run_QM¶

Type [bool or list]

This attribute set a first set of selection to the molecule which should be QM-treated. Indeed, you may want to not perform for all the molecule of a MT QM calculations: it may be too much time-consuming for litle interest. Therefore, this attribute works very similary to the DiagramParameter.special_selection. Another selection can be added in top of this one usin the attribute OpticalParameter.selection_tool. The molecule that will be QM computed have to respect all the 3 attributes restrictions.

The format of this attribute is very similar to the geometrical discretisation option when declaring a diagram. As an user, when declaring list of diagram to performed, you can define this special geometrical selection using:

myMT.read_optic_properties_input(GP, ...,  where_to_run_QM=where_to_run_QM)

Here are the available values for where_to_run_QM:

False or True:

No extra special selection is made. All the molecule of the MT may be QM treated.

In this case, the OpticalParameter.where_to_run_QM attribute is set to [-1].

[‘All’]:

No extra special selection is made. All the molecule of the MT may be QM treated.

In this case, the OpticalParameter.where_to_run_QM attribute is set to [-1].

[‘Plane_ij’, bin_number, list_of_bin]:

For each time step, the box is discretized along plane with the axis ij. bin_number number of bin is used. Every molecules are assigned to one of these bin according to there mean position. If this bin is within the list_of_bin, the molecule is QM treated.

In this case, the OpticalParameter.where_to_run_QM attribute is set to [axis where the space is decretize (0, 1 or 2), bin_number, list_of_bin]

[‘Layer’, nbr_layer, list_layer]:

For each time step, the molecule are assigned to a layer, using ‘nbr_layer’ number of layer. If a molecule is in the layer number given by list_layer, it is QM-treated.

In this case, the OpticalParameter.where_to_run_QM object is set to [10, 2*nbr_layer+1, list_layer]

Example

myMT.read_optic_properties_input(GP, ...,  where_to_run_QM=['Plane_xy', 100, [60, 61, 62, 63, 64, 65, 66]], ...)

where the ‘…’ stands for the other parameter you may need to use.

The box in discretize along the z axis using 100 bins. Only the molecule within the 60 to 66 bin are treated using QM. The other molecule will have a null value regarding the optical analysis based on QM calculation. For instance, if OpticalParameter.beta_calculation_style = ‘QM’, the molecule which does not respect the previous condition will have for beta and chi 3x3x3 matrices with only zero values.

Note that the list of authorized bin can be not continous.

Example

where_to_run_QM = [‘Layer’, 4, [-4, -3, 0, 1, 4]]

Here, nbr_layer = 4. A molecule can be assigned to the layer number 4, 3, 2 or 1 for the upper interface (the 1st is the closest to the bulk phase, the 4th the farthest), to -4, -3, -2, -1 for the lower interface (the -4 is the farest from the bulk phase) or to 0 for the molecule in the bulk-like phase. Only molecule with layer number -4, -3, 0, 1 or 4 will be QM-treated using Dalton.

Note that the list of authorized layer can be not continous.

Note

This condition is made after the one regarding the diagram parameters – given by DiagramParameter.special_selection .

Note

This selection does not affect the diagram space discretization. Keep just in mind that if a molecule does not respect the OpticalParameter.where_to_run_QM conditions, its optical value may be zeros. Therefore, the total diagram can contains molecules which are QM-treated, and other with zero values.

Note

For develloper: the concrete action of OpticalParameter.where_to_run_QM is made in geometry_manager.optparameter_where_to_run_QM_molecule. Use this function to update new option for this attribute.

class Frog.class_OpticalParameter.QMDescription[source]¶

Bases: object

Variable defined by the molecular module: - L_coordinate: [list of 3D array] The position of the atom described in the L_atom_type. Note that L_coordinate can be similar to the position given by the MD (with respect for the order of the atom for instance), but may be not depending on the molecular module function electrostatic_description. - L_atom_type: [list] The list of the atom in the molecule which contains the charge, the name and the localization with respect to the L_coordinate nomenclature used. Example: If the L_coordinate provide for a water molecule the coordinate in the order: Oxygen, Hydrogen, Hydrogen; then: [[8, 1, [‘0’, 0]], [1, 2, [‘H’, 1], [‘H’, 2]]]. [8, 1, [‘0’, 0]] is for: [charge, occurence in the molecule, [name of the atom, position in the coordiante provided by the L_coordinate]]. Please do not use fency name for the atom (like O_1, H_c2 ect…). Otherwise, it may lead to problem when using the calculation style ‘PE + QM box’ if different molecule type have to be put in the same QM box.

property L_atom_type¶

Type [list]

Atribute defines in the qm_target_description molecular library function.

QMDescription.L_atom_type contains the the atom type name and the number of electrons associated.

Example

For Water: QMDescription.L_atom_type = [[8, 1, [[‘O’, 0]]], [1, 2, [[‘H’, 1], [‘H’, 2]]]]

The QMDescription.L_atom_type is composed of list. Each sub-list described one type of atom. For instance, for Water there are 2 atom type: [8, 1, [[‘O’, 0]]] and [1, 2, [[‘H’, 1], [‘H’, 2]]].

The format is: [Nbr electron, Nbr of this atom type, [[name for this atom, index in the coordinate], [name for this atom, index in the coordinate], …]]]

The first list described the Oxygen atom. There is 8 electrons per atom and 1 Oxygen in this molecule. The atom is named ‘O’ in the molecule.mol file, and its coordinate is given by: QMDescription.L_coordinate[0]

The second list described the Hydrogen atom. There is 1 electrons per atom and 2 Hydrogen in this molecule. The first atom is named ‘H’ in the molecule.mol file, and its coordinate is given by: QMDescription.L_coordinate[1]. The second atom is also named ‘H’ in the molecule.mol file, and its coordinate is given by: QMDescription.L_coordinate[2]

Another example of a Methanol molecule: QMDescription.L_atom_type = [[8, 1, [[‘O’, 0]]], [1, 4, [[‘H’, 1], [‘H’, 3], [‘H’, 4], [‘H’, 5]]], [6, 1, [[‘C’, 2]]]]

There are 3 type of atom: Oxygen, Hydrogen and Carbon.

The first list described the Oxygen atom. There is 8 electrons per atom and 1 Oxygen in this molecule. The atom is named ‘O’ in the molecule.mol file, and its coordinate is given by: QMDescription.L_coordinate[0].

The second list described the Hydrogen atom. There is 1 electrons per atom and 4 Hydrogen in this molecule. The all the Hydrogen are named ‘H’ in the molecule.mol file, and their coordinates are given by: QMDescription.L_coordinate[1], QMDescription.L_coordinate[3], QMDescription.L_coordinate[4], QMDescription.L_coordinate[5].

The third list described the Carbon atom. There is 6 electrons per atom and 1 Carbon in this molecule. The atom is named ‘C’ in the molecule.mol file, and its coordinate is given by: QMDescription.L_coordinate[2].

Note

If you are using QMParameter.calculation_style = ‘PE + QM’, try to use (or modify) the same atom name to make easier the creating of graps. For instance, defines all the Oxygen using ‘O’, all the Hydrogen using ‘H’ …

property L_coordinate¶

Type [list]

Atribute defines in the qm_target_description molecular library function.

QMDescription.L_coordinate contains the the atom position in the laboratory frame. The position shall be expressed in Angstrom.

merge_mol(otherself)[source]¶: TODO

nbr_type_atom()[source]¶: Return the number of different atom type.

class Frog.class_OpticalParameter.QMParameter[source]¶

Bases: object

Contains all the information to perform QM calculation for this molecule type. Many of them are directly link to Dalton variable. The rest for the environment building from the MD trajectory. Very important parameters are read from the molecular module of this molecule type. Please make sure that the nomenclature used by the MD simulation is the same as the one used in the molecular module.

Recommendations:

We strongly advice to check the environment built by setting the variable write_xyz_environment to True. Many insights are provided when watching to the molecular conformation. Moreover, it may highlight issues – for instance PBC ones if the MD box size is not large enough.

Read the Dalton inputs generated by the software and try to run one conformation before sending hundred of crashing code to the cluster. Take some time to read the (clear and insightfull!) Dalton documentation.

Take some time to converge the basis set you are using with respect to the observable. Espcially if you are interested in SHG processes.

Variable defined by the user:

dalton_version : [float] giving the year or the version name. Default = 2020

calculation_style: [string] Set the type of environement for a molecule. Possible value: ‘Vacuum’, ‘PE’, ‘PE + QM box’.
Vacuum means that the QM calculation will be performed assuming that the molecule has no environment – gas phase like calculation.

The PE means that the QM box will contains only the molecule, but the QM box is embedded in an electrostatic environment. The electrostatic environement is described classically.

The PE + QM box means that the QM box may contains several molecules, and the QM box is embedded in an electrostatic environment. The electrostatic environement is described classically.

pe_level: [integer] -1 for vaccum, 0 for non polarizable environment (the charges of the environement are fixed), 1 for polarizable environment (the environement is polarizable). Please note that the ‘1’ has not been tested yet.

max_pe_distance_neigh: [float] If QM calculation in an PE environement is set, define the maximal distance from the target molecule to find neighbourgs which participate to the electrostaic environment.

max_pe_polarization_distance_neigh: TODO

max_qm_box_distance_neigh: [float] If QM calculation in an PE environement is set, define the maximal distance from the target molecule to find neighbourgs which participate to the electrostaic environment.

write_xyz_environment: [boolean] Set if the environment of the molecule used to creat the electrostatic environment should be printed. By default set to False.

theory_lv: [string] The theoretical scheme used to perform the QM calculation. Possible value: DFT.

functional: [string] If the theory_lv = DFT, set the functional for the QM calculation.

type_basis: [string] The way basis set are describing a molecule (for all the atom or per atom). Implemented: Global basis.

global_basis_value: [string] The Dalton basis set used to described all the atom of the molecule type. Please note that several basis set can be defined if several molecule type are used (one per molecule type).

polarizability_response: [list or boolean] Define if the first polarizability of the molecule should be calculated. By default, set to False. If the polarizability should be computed, the polarizability_response should be a list of the frequency it has to be computed (in atomic unit). Example: polarizability_response = [0.0, 0.05686] to compute the static polarizability (0 frequency) and the one at 800 nm (0.05686 frequency).

shg_response: [list or boolean] Define if the first hyperpolarizability of the molecule should be calculated. By default, set to False. If the hyperpolarizability should be computed, the polarizability_response should be a list of the fundamental frequency it has to be computed (in atomic unit). Example: polarizability_response = [0.0, 0.05686] to compute the static polarizability (0 frequency) and the one at 800 nm (0.05686 frequency).

beta_order = [str] ‘dipole’ or ‘quadrupole’, see optparameter.beta_order for more details.

total_charge: [integer] The total charge of the molecule type. By default, all the molecule have a zero-charge. Can be positive or negative. Please note that if the ‘PE + QM box’ calculation style is used.

static_electric_field: [list of float] If defined, set a global static electric field to the quantum box.

max_iter_scf: [integer] The maximal scf iteration for the ground state calculation. By default, set to 500.

restart: [boolean] Set if Dalton tries to restart from a previous results/data. Actually not implemented, by default set to False.

Internal Variable:

RUN_*: [boolean] Intern variable used to write the dalton input file.
more_select_environment: [boolean or string]

property 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!

property RUN_electric_field¶

Type [bool]

Not user defined

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

Set to True if any homogenous electrostatic field has to be added to the QM box.

property RUN_integral¶

Type [bool]

Not user defined

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

property 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 .

property RUN_polarization¶

Type [bool]

Not user defined

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

Set to True if the polarizability has to be computed.

property 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 .

property RUN_response¶

Type [bool]

Not user defined

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

Set to True if any optical property has to be computed.

property RUN_shg¶

Type [bool]

Not user defined

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

Set to True if the hyperpolarizability has to be computed.

property 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.

check_input_qm(optparameter, GP)[source]¶: Check if the input are incoherent and print messages to show what the software have understood. Initialized some internal variables used later on when writting the Dalton inputs for the conformations.

property dalton_version¶: Type [float] Set the Dalton version, typically the year of release (2018, 2020, ..) with some under-version numbers

property effective_field_polarization¶

Type [bool]

Not user defined

Originaly designed for effective field (cavity field) calculation. Today not implemented. Shall remain False.

property 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)

property 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.

property 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.

property 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.

property long_range_switch¶

Type [Bool]

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

Intern variable set by Frog. If set to True, some neighbors can be part of the ‘long range’ environment. If False, such case cannot happened. This variable is usefull for code lisibility/efficiency

property max_iter_scf¶

Type [int]

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

By default set to 500

property 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.

property 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.

property 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!

merge_qmparameter(otherself, GP)[source]¶: Merge the theory description in the case of PE + QM box type of calculation: several molecule in the QM box. This is done so that only one type of theory description is used for both molecules.

property 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.

property 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]

property 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.

property 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.

property 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

property 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).

property 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.

property 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)

property 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.

property 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.

property 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.

property 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.

7.8. Frog.class_modules module¶

class Frog.class_modules.SingleMoleculeParameter[source]¶

Bases: object

property L_type_atom¶

Type [list]

The list of atom. The size of L_type_atom should be equal to nbr_atom.

Note

The list can be completly different from the labelling of the MD. This labelling is used for user-friendly prints only.

Note

The name can de different from the one of qm_target_description and electrostatic_description.

property d_molecular_orientation¶

Type [int]

The number of number needed to defined the ‘orientation’ of the molecule in the laboratoy frame. You can go from 1 to N.

Example

For the water molecule, you can define the orientation using 3 ‘angles’.

For more complexe molecule, you can use many more ‘angles’.

property max_distance_atom¶

Type [list]

Defines maximal distance for every atom with respect to a ‘’reference’’ atom. The aim is to help Frog to deal with ‘cutted’ molecule due to PBC condition.

This value should be a list: [The ‘’reference’’ atom, Value for atom 0, Value for atom 1, …].

Where “Value for atom 0” should be ‘Ref’ or the maximal distance allowed from the ‘’reference’’ atom. Note that the atom numerotation starts from 0. If one atom of a molecular trajectory does not respect this maximal distance from the reference atom, Frog tries to move it using the box size of the MD simulation at the given time step. Thus, it is important to be strict enough with respect to these distance – being too restrictive will lead to crashes (with error message) if Frog fails to respect these conditions.

Example

For water, L_type_atom = [O, H, H], one can set:

max_distance_atom = [0, ‘Ref’, 2, 2]

The Oxygen atom is the reference atom, and the Hydrogens should not be more away from it then 2 Angstrom.

property name_mt¶

Type [str]

The name of the MT used to defined this ensemble. Should be the same as the libreary molecular file and the MT.

property nbr_atom¶

Type [int]

The number of atom of this molecule type.

Example

For water, if the MD provides the atom position set nbr_atom to 3.

If the MD provides also the position of the dipole, you should set as many ‘atom’ as position stored in the MD trajectory – so maybe 4.

property size_typical_molecule¶

Type [float]

A typical value of the size of the molecule. The idea is to help Frog to reconstruct the geometry of the molecule is PBC condition are applied. If also help Frog to find neighborgs.

Example

For water, you can set size_typical_molecule to 2 Angstrom.

Frog.class_modules.give_class_diagram_name(type_diagram)[source]¶: dummy function to avoid trouble later if the name of the Diagrams changes

7.9. Frog.dalton_manager_module module¶

Frog.dalton_manager_module.build_QM_file_localization(path_QM_dir, moleculetype_name, time, molecule_number, creat_dir=False)[source]¶

Define how the directory name is created/attributed for the QM run knowing target molecule attributes – for instance the time step or the molecule type name. Also creat the directory if needed

Today, the localisation for the QM calculation of the ‘i’ molecule at the time step ‘T’ of the molecule type ‘Mol’ would be: GP.dir_torun_QM/Mol/Time_T/Molecule_i.

Frog.dalton_manager_module.check_if_run_already_performed(GP, moleculetype_name, time, molecule_number)[source]¶

Check if the QM calculation of this molecule is already performed.

If is_the_calculation_done = True, the calculation has been done. QM_file_localization_name is the directory where the QM calculation should be done.

Frog.dalton_manager_module.check_if_run_done(name_dir)[source]¶: Check whether the QM calculation has been perform ‘’successfully’. Here we use the fact that the CPU and Wall time is suposed to be given at the end of the Dalton run. Maybe there are easier way to achieve that. Note that this function does not check if the polarizability/hyperpolarizability has been computed!

Frog.dalton_manager_module.create_submissionfile_array(GP, total_job_number, new_psmn=True)[source]¶: TODO

Frog.dalton_manager_module.fill_2nd_order_tensor(L_beta, beta, value)[source]¶

Frog.dalton_manager_module.fill_beta_dipole_quadru(L_chi, L_info_one_component)[source]¶

Frog.dalton_manager_module.fill_beta_quadru_dipole(L_chi, L_info_one_component)[source]¶

Frog.dalton_manager_module.fill_beta_quadru_zero_freq(L_chi, L_info_one_component)[source]¶

Frog.dalton_manager_module.find_1st_order_tensor_component(L_iota_raw)[source]¶

Find the component of the first order response tensor in the case of dipole-dipole interaction. In other words the polarizability.

In the Dalton output file, there can be also dipole-quadrupole response tensor (for the first hyperpolarizability calculation later on). We are not interested in these quantity, so i or j = -1 in this case

Frog.dalton_manager_module.find_2nd_order_tensor(char)[source]¶: Remark: in the dalton output, the name is ‘’beta’’, evenif it is chi.

Frog.dalton_manager_module.find_beta_dipole_quadru(L_chi, L_info_one_component, frequency)[source]¶: Here we record only: <mu, mu, Q> Note: at zero-frequency: <Q, mu, mu>

Frog.dalton_manager_module.find_beta_quadru_dipole(L_chi, L_info_one_component, frequency)[source]¶: Here we record only: <Q, mu,mu> Note: at zero-frequency: <Q, mu, mu>

Frog.dalton_manager_module.generate_inp_dal(qmparameter, filename, molecular_electric_field=False)[source]¶: Generate the .dal input file depending on the parameters given

Frog.dalton_manager_module.generate_inp_mol(qmparameter, filename, qmdescription, message_1=False, message_2=False)[source]¶: Generate the .mol dalton input file for the given molecule or graps of molecule. Note that this is given in the laboratory frame.

Frog.dalton_manager_module.generate_inp_pot(electro_neigh, filename, xyz_environemnt=False)[source]¶: Create the .pot input file for a given molecule electrostatic environment. Note that this is given in the lboratory frame.

Frog.dalton_manager_module.load_chi(QM_dir_mol, frequency, beta_type, marker='')[source]¶

Load the first hyperpolarizability from the Dalton output.

The reading depends on the type of beta defiend by , beta_type. If it is ‘dipole-dipole’, Dalton provide easely the answer. Otherwise for the ‘dipole-quadrupole’ and ‘quadrupole-dipole’ there is bit more work.

IMPORTANT: no change of sign/convention is made here!!!! This function only read the information from Dalton. IMPORTANT: depending on the frequency and the type of beta, the Kleinman symetry may be inforced here. Note that the dipole-quadrupole and quadrupole-beta behaves differently from the usual dipole-dipole hyperpolarizability. For more informatioin please read the documentation about the convention/definition of the hyperpolarizability in Frog!

Frog.dalton_manager_module.load_iota(QM_dir_mol, frequency)[source]¶: Read the polarizabiliy value at the given frequency from the dalton output file named QM_dir_mol.

Frog.dalton_manager_module.load_iota_from_1st_order_calculation(temp_file_name, L_frequency)[source]¶

Frog.dalton_manager_module.load_iota_from_2nd_order_calculation(temp_file_name, L_frequency)[source]¶

Frog.dalton_manager_module.move_previous_results(GP, moleculetype_name, time, molecule_number)[source]¶: If GP.redo_QM == ‘redo’, this function is called to move the already existing dalton results.

Frog.dalton_manager_module.print_info_QM_file_localization()[source]¶

Frog.dalton_manager_module.return_component_dipole(XYZ)[source]¶

Frog.dalton_manager_module.return_component_quadrupole(IJ)[source]¶

Frog.dalton_manager_module.submit_qm_calculation(GP, name_file_submit, dir_QM, template_ready_to_copy, trotter, new_psmn=True)[source]¶: Create the submission scripts used to run Dalton on the cluster. This function may be modified for you particular cluster needs!

Frog.dalton_manager_module.symetryse_beta_dipole_quadrupole(L_chi, value, i, j, k, l, frequency_zero=False)[source]¶

Frog.dalton_manager_module.symetryse_beta_quadrupole_dipole(L_chi, value, i, j, k, l)[source]¶

Frog.dalton_manager_module.write_beta_quadrupole_dalton_shortcut(the_file)[source]¶: Function used to make the main part of the code more readable

7.10. Frog.electric_field_module module¶

Frog.electric_field_module.add_single_contribution_electric_field_pbc(electro_description, L_box_vector=False)[source]¶: Compute the electric field generated by a (single) molecule electrostatic description at the zero order, and its periodic images. The results is given in atomic unit.

Frog.electric_field_module.compute_electric_field_from_electro_description(electro_description, pos_of_interest)[source]¶

Frog.electric_field_module.compute_electric_field_on_fly(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, residue_nbr, mean_position)[source]¶: TODO

Frog.electric_field_module.electric_field_from_one_order_0_description(pos_of_interest, charge_value, pos_charge)[source]¶: Return the electric field generated by a point charge. Note that some prefactor may be add depending of the unit. dE[j][i] = d E_i / d x_j

Frog.electric_field_module.to_store_electric_field(electric_field_lab, d_electric_field_lab, rot_matrix, style='direct', E_long=False, dE_long=False)[source]¶

Used as a shortcut to store the obtained electric field and derivative in the smolecule object.

The electric field stored can depend on the style use.

7.11. Frog.error_messages module¶

exception Frog.error_messages.NotAnOptionError[source]¶: Bases: Exception

Frog.error_messages.e_100(pos_tomove, pos_ref, max_norm, L_pbc_parameter, pos_temp)[source]¶

Frog.error_messages.e_101(GP)[source]¶

Frog.error_messages.e_102(moleculetype, molecule_type_module, L_traj_shape)[source]¶

Frog.error_messages.e_103(dparameter)[source]¶

Frog.error_messages.e_104()[source]¶

Frog.error_messages.e_105(sdparameter)[source]¶

Frog.error_messages.e_106(smparameter, sdparameter)[source]¶

Frog.error_messages.e_107()[source]¶

Frog.error_messages.e_108()[source]¶

Frog.error_messages.e_109()[source]¶

Frog.error_messages.e_110(GP)[source]¶

Frog.error_messages.e_111()[source]¶

Frog.error_messages.e_112()[source]¶

Frog.error_messages.e_113()[source]¶

Frog.error_messages.e_114()[source]¶

Frog.error_messages.e_115()[source]¶

Frog.error_messages.e_116()[source]¶

Frog.error_messages.e_117()[source]¶

Frog.error_messages.e_118(qmparameter)[source]¶

Frog.error_messages.e_119()[source]¶

Frog.error_messages.e_120()[source]¶

Frog.error_messages.e_121()[source]¶

Frog.error_messages.e_122()[source]¶

Frog.error_messages.e_123()[source]¶

Frog.error_messages.e_124()[source]¶

Frog.error_messages.e_125()[source]¶

Frog.error_messages.e_126()[source]¶

Frog.error_messages.e_127_a()[source]¶

Frog.error_messages.e_127_b()[source]¶

Frog.error_messages.e_128_a()[source]¶

Frog.error_messages.e_128_b()[source]¶

Frog.error_messages.e_129()[source]¶

Frog.error_messages.e_130()[source]¶

Frog.error_messages.e_131()[source]¶

Frog.error_messages.e_132()[source]¶

Frog.error_messages.e_133(GP)[source]¶

Frog.error_messages.e_134_a(submissionfilename)[source]¶

Frog.error_messages.e_134_b(submissionfilename)[source]¶

Frog.error_messages.e_134_c(GP, total_job_number, submissionfilename)[source]¶

Frog.error_messages.e_135()[source]¶

Frog.error_messages.e_136()[source]¶

Frog.error_messages.e_137()[source]¶

Frog.error_messages.e_138()[source]¶

Frog.error_messages.e_139()[source]¶

Frog.error_messages.e_140()[source]¶

Frog.error_messages.e_141()[source]¶

Frog.error_messages.e_142()[source]¶

Frog.error_messages.e_143()[source]¶

Frog.error_messages.e_144()[source]¶

Frog.error_messages.e_145()[source]¶

Frog.error_messages.e_146()[source]¶

Frog.error_messages.e_147()[source]¶

Frog.error_messages.e_148()[source]¶

Frog.error_messages.e_149()[source]¶

Frog.error_messages.e_150()[source]¶

Frog.error_messages.e_151()[source]¶

Frog.error_messages.e_152()[source]¶

Frog.error_messages.e_153()[source]¶

Frog.error_messages.e_154()[source]¶

Frog.error_messages.e_155()[source]¶

Frog.error_messages.e_156()[source]¶

Frog.error_messages.e_157()[source]¶

Frog.error_messages.e_158()[source]¶

Frog.error_messages.e_159()[source]¶

Frog.error_messages.e_90()[source]¶

Frog.error_messages.e_91()[source]¶

Frog.error_messages.e_92()[source]¶

Frog.error_messages.e_94()[source]¶

Frog.error_messages.e_95(name_save)[source]¶

Frog.error_messages.e_96(unable_return)[source]¶

Frog.error_messages.e_97(unable_return)[source]¶

Frog.error_messages.e_98()[source]¶

Frog.error_messages.e_99(diagram, otherdiagram)[source]¶

7.12. Frog.first_part module¶

Frog.first_part.treat_block_of_frame(time_step_management, L_dict)[source]¶: Treat each frame and write the result in the GP.dir_mol_times directory.

Frog.first_part.treat_one_frame(GP, L_moleculetype, time_step)[source]¶: Perform all the analysis which do not involve QM results nor the effective field calculation. Prepare the QM inputs and update the list of the QM calculation to perform. Not that if this function is called, previous results may be deleted since the new L_molecule_time (computed here) will be saved using the same name.

7.13. Frog.frog_class module¶

7.14. Frog.frog_data_analysis module¶

Frog.frog_data_analysis.gaussian_fct(x, max_y, x_0, sigma)[source]¶

Frog.frog_data_analysis.gaussian_fit(x, y)[source]¶

Frog.frog_data_analysis.load_result(directory, name_result='L_moleculetype_result.p', what_to_print=False)[source]¶

Frog.frog_data_analysis.print_diagram_info(GP, L_moleculetype_result)[source]¶

Frog.frog_data_analysis.print_general_info(GP, L_moleculetype_result)[source]¶

Frog.frog_data_analysis.return_diagram(GP, L_moleculetype_result, MT_name, name_diagram)[source]¶

7.15. Frog.geometry_manager module¶

class Frog.geometry_manager.PBC(GP, ts)[source]¶: Bases: object

Frog.geometry_manager.check_molecule_geometry(smparameter, L_pos_mol, L_box_size)[source]¶: Check that their are no PBC problems within the molecule. The L_max_norm array is the parameters to tune to set the maximal accepted distance between the first atom and the others - distance given in the same unit as the molecular position. If the distance btween one atom and the first one is larger than the accepted value, the program will try to reduce this distance by using PBC condition.

Frog.geometry_manager.compute_angle_3_atoms(L_angle)[source]¶: Compute the angle between 3 atoms. The angle is return in radians.

Frog.geometry_manager.discretization_space(GP, smolecule, sdparameter, L_box_size)[source]¶: Return the spatial bin for a molecule according to the spatial discretization of the diagram.

Frog.geometry_manager.find_closest_position_threw_pbc(L_target, L_neigh, L_box_size, L_box_authorised)[source]¶: Return the shift to apply to the L_neigh position so that it is the closest to the L_target position using the PBC condition available in L_box_size.

Frog.geometry_manager.init_plane_axis(L_xyz_todo, box_size, nbr_bin_space)[source]¶: This function return some software friendly parameter from humain-frendly inputs during diagrams initialization.

Frog.geometry_manager.optparameter_selection_tool_molecule(GP, moleculetype, kkk)[source]¶

Used to allow molecule to be treated or not depending on the moleculetype.mtparameter.optparameter.selection_tool option. This function is very quite different from the discretization_space one

This function has been made to make the Prepare_run_QM (fake) diagram lighter to read. Make sure to update it if you implement any new moleculetype.mtparameter.optparameter.selection_tool option.

Frog.geometry_manager.optparameter_where_to_run_QM_molecule(GP, moleculetype, kkk, L_box_size)[source]¶

Used to allow molecule to be treated or not depending on the moleculetype.mtparameter.optparameter.where_to_run_QM option. This function is very similar to the discretization_space one: it uses the space discretization procedure to return a ‘bin’ for every molecule. If the bin has been authorized by the user, the molecule is treated.

This function has been made to make the Prepare_run_QM (fake) diagram lighter to read. Make sure to update it if you implement any new moleculetype.mtparameter.optparameter.where_to_run_QM option.

Frog.geometry_manager.pbc_condition(pos_ref, pos_tomove, max_norm, L_pbc_parameter)[source]¶: This function move the target atom at the position < pos_tomove > closer to the reference one < pos_ref > if their distance is larger than < max_norm >. To achieve that, it uses the vector < L_pbc_parameter > assuming periodic boundary condition in the 3 directions. Returns the moved positions of the target atom.

Frog.geometry_manager.selection_absolute_position(L_list_name_MT, L_neighbourhood_names_number, L_environment, L_target_mean_pos, qmparameter, GP, L_moleculetype)[source]¶: TODO

Frog.geometry_manager.selection_relative_position(L_list_name_MT, L_neighbourhood_names_number, L_environment, qmparameter, GP, L_moleculetype)[source]¶: TODO

Frog.geometry_manager.special_selection_assignement_for_molecules(GP, moleculetype, L_box_size)[source]¶

Used to allowed molecule to be treated or not depending on the moleculetype.mtparameter.dparameter.special_selection option. This function is very similar to the discretization_space one: it uses the space discretization procedure to return a ‘bin’ for every molecule. If the bin has been authorized by the user, the molecule is treated.

This function has been made to make the first part lighter to read. Make sure to update it if you implement any new moleculetype.mtparameter.dparameter.special_selection option.

7.16. Frog.main module¶

Frog.main.frog_run(input_file)[source]¶

The programme to call to start anything. First, it reads the input file – the argument of this function. Then, 3 parts can be run:

First Part:
Perform trajectory analysis which does not involve QM calculations and/or prepare the scripts needed to perform QM calculations. The results are stored for every frame.
Second Part:
If any QM calculations have to be performed, check how many run should be launched. Depending on the options, some runs can be skipted or redone. The output of this part will be scripts cluster-intended. The user has to launch the QM run in the cluster manually after the end of this second part. If any QM calculation has to be performed at the end of the second part, the last part is not run and the software stops.
Third Part:
If QM calculation has been performed, read the results and stored them. Finally, merged the results of each frame and performed statistical analysis if asked.

Frog.main.frog_run_from_shell()[source]¶: Function to run FROG from non-python environement, typically from the shell.

Frog.main.launch_first_part(GP, L_moleculetype)[source]¶: Perform the MD analysis and prepare the QM run. If several core are available, run in parrallel.

Frog.main.launch_second_part(GP)[source]¶

Prepare the script used to run the QM calculations on a cluster. First read/check how many QM calculations have been performed / have to be performed Then, if any left to do, write scripts to launch them.

If QM calculations should be performed, the FROG run ends at the end of this function. Otherwise, the FROG run continues with the third part.

Frog.main.launch_third_part(GP)[source]¶

Read the QM results and store them into the diagrams.

Then, perform averaging over all the time step.

This function can be run in parralelle.

Frog.main.read_input(file)[source]¶: Read the input file and initialize the run.

7.17. Frog.messages module¶

Frog.messages.frog_authors()[source]¶

Frog.messages.frog_licence()[source]¶

Frog.messages.frog_logo()[source]¶

Frog.messages.frog_title()[source]¶

Frog.messages.initial_msg_welcome()[source]¶: Opening message of the software. Please keep this function the clearest and simplest possible: use sub-functions.

Frog.messages.message_with_hashtag(nbr_hashtag, nbr_line_hashtag, message)[source]¶

Print the message with extra #. Exemple: main_part_message_block(30, 1, ‘hello everyone’) will print:

############################## ####### hello everyone ####### ##############################

Frog.messages.strong_remarks()[source]¶

Frog.messages.user_frendly_1(input_file)[source]¶

Frog.messages.user_frendly_10()[source]¶

Frog.messages.user_frendly_11(toprint)[source]¶

Frog.messages.user_frendly_12()[source]¶

Frog.messages.user_frendly_13(direction_toprint, L_input_diagram, slice_size, nbr_bin_space)[source]¶

Frog.messages.user_frendly_14_a(smparameter, sdparameter)[source]¶

Frog.messages.user_frendly_14_b(smparameter, sdparameter)[source]¶

Frog.messages.user_frendly_15(sdparameter, smparameter)[source]¶

Frog.messages.user_frendly_16(sdparameter, info_mol)[source]¶

Frog.messages.user_frendly_17(smparameter, info_mol)[source]¶

Frog.messages.user_frendly_18(sdparameter)[source]¶

Frog.messages.user_frendly_19(sdparameter)[source]¶

Frog.messages.user_frendly_2(GP)[source]¶

Frog.messages.user_frendly_20(sdparameter)[source]¶

Frog.messages.user_frendly_21(sdparameter)[source]¶

Frog.messages.user_frendly_22()[source]¶

Frog.messages.user_frendly_23()[source]¶

Frog.messages.user_frendly_24_a()[source]¶

Frog.messages.user_frendly_24_b()[source]¶

Frog.messages.user_frendly_25()[source]¶

Frog.messages.user_frendly_26(L_alpha_ref)[source]¶

Frog.messages.user_frendly_27()[source]¶

Frog.messages.user_frendly_28()[source]¶

Frog.messages.user_frendly_29(optparameter)[source]¶

Frog.messages.user_frendly_3()[source]¶

Frog.messages.user_frendly_30()[source]¶

Frog.messages.user_frendly_31(where_to_run_QM)[source]¶

Frog.messages.user_frendly_32()[source]¶

Frog.messages.user_frendly_33(direction_toprint, nbr_bin_space, where_to_run_QM)[source]¶

Frog.messages.user_frendly_34_a()[source]¶

Frog.messages.user_frendly_34_b()[source]¶

Frog.messages.user_frendly_34_c()[source]¶

Frog.messages.user_frendly_34_d()[source]¶

Frog.messages.user_frendly_35(qmparameter)[source]¶

Frog.messages.user_frendly_36()[source]¶

Frog.messages.user_frendly_37()[source]¶

Frog.messages.user_frendly_38(qmparameter)[source]¶

Frog.messages.user_frendly_39(GP)[source]¶

Frog.messages.user_frendly_4()[source]¶

Frog.messages.user_frendly_40(qmparamter)[source]¶

Frog.messages.user_frendly_41()[source]¶

Frog.messages.user_frendly_42_a(qmparamter)[source]¶

Frog.messages.user_frendly_42_b(qmparamter)[source]¶

Frog.messages.user_frendly_43(qmparameter)[source]¶

Frog.messages.user_frendly_44(qmparameter)[source]¶

Frog.messages.user_frendly_45(qmparameter)[source]¶

Frog.messages.user_frendly_46()[source]¶

Frog.messages.user_frendly_47(qmparameter)[source]¶

Frog.messages.user_frendly_48()[source]¶

Frog.messages.user_frendly_49(qmparameter)[source]¶

Frog.messages.user_frendly_5()[source]¶

Frog.messages.user_frendly_50_a(name_save)[source]¶

Frog.messages.user_frendly_50_b(name_pickle)[source]¶

Frog.messages.user_frendly_51_a(dir_type)[source]¶

Frog.messages.user_frendly_52_a(GP)[source]¶

Frog.messages.user_frendly_52_b(path_working_dir)[source]¶

Frog.messages.user_frendly_53_a(GP)[source]¶

Frog.messages.user_frendly_53_c(GP)[source]¶

Frog.messages.user_frendly_54_a(GP)[source]¶

Frog.messages.user_frendly_54_b(GP)[source]¶

Frog.messages.user_frendly_54_c(GP)[source]¶

Frog.messages.user_frendly_55_a(GP)[source]¶

Frog.messages.user_frendly_55_b(GP)[source]¶

Frog.messages.user_frendly_55_c(dir_QM_exemple_name)[source]¶

Frog.messages.user_frendly_56_a(GP)[source]¶

Frog.messages.user_frendly_56_b(GP)[source]¶

Frog.messages.user_frendly_56_c(GP)[source]¶

Frog.messages.user_frendly_57(GP)[source]¶

Frog.messages.user_frendly_58_a()[source]¶

Frog.messages.user_frendly_58_b(GP)[source]¶

Frog.messages.user_frendly_59(GP)[source]¶

Frog.messages.user_frendly_6(GP)[source]¶

Frog.messages.user_frendly_60_a()[source]¶

Frog.messages.user_frendly_60_b()[source]¶

Frog.messages.user_frendly_60_c()[source]¶

Frog.messages.user_frendly_61_a()[source]¶

Frog.messages.user_frendly_61_b()[source]¶

Frog.messages.user_frendly_62_a()[source]¶

Frog.messages.user_frendly_62_b()[source]¶

Frog.messages.user_frendly_62_c(GP)[source]¶

Frog.messages.user_frendly_63_a()[source]¶

Frog.messages.user_frendly_63_b(GP)[source]¶

Frog.messages.user_frendly_63_c(GP)[source]¶

Frog.messages.user_frendly_63_d(GP)[source]¶

Frog.messages.user_frendly_64(GP, L_moleculetype)[source]¶

Frog.messages.user_frendly_65()[source]¶

Frog.messages.user_frendly_66_a(GP)[source]¶

Frog.messages.user_frendly_66_b(GP, time_step)[source]¶

Frog.messages.user_frendly_66_c()[source]¶

Frog.messages.user_frendly_67_a()[source]¶

Frog.messages.user_frendly_67_b()[source]¶

Frog.messages.user_frendly_67_c()[source]¶

Frog.messages.user_frendly_68_a(GP)[source]¶

Frog.messages.user_frendly_68_b(GP)[source]¶

Frog.messages.user_frendly_69(GP)[source]¶

Frog.messages.user_frendly_7(GP)[source]¶

Frog.messages.user_frendly_70(GP, name_array_script_job)[source]¶

Frog.messages.user_frendly_71_a(submissionfilename)[source]¶

Frog.messages.user_frendly_71_b(submissionfilename)[source]¶

Frog.messages.user_frendly_71_c(GP, total_job_number, submissionfilename)[source]¶

Frog.messages.user_frendly_72()[source]¶

Frog.messages.user_frendly_73()[source]¶

Frog.messages.user_frendly_74()[source]¶

Frog.messages.user_frendly_75()[source]¶

Frog.messages.user_frendly_76()[source]¶

Frog.messages.user_frendly_77()[source]¶

Frog.messages.user_frendly_78()[source]¶

Frog.messages.user_frendly_79()[source]¶

Frog.messages.user_frendly_8(moleculetype)[source]¶

Frog.messages.user_frendly_80()[source]¶

Frog.messages.user_frendly_81()[source]¶

Frog.messages.user_frendly_82()[source]¶

Frog.messages.user_frendly_83()[source]¶

Frog.messages.user_frendly_84()[source]¶

Frog.messages.user_frendly_85()[source]¶

Frog.messages.user_frendly_86()[source]¶

Frog.messages.user_frendly_87()[source]¶

Frog.messages.user_frendly_88()[source]¶

Frog.messages.user_frendly_89()[source]¶

Frog.messages.user_frendly_9(moleculetype, molecule_type_module)[source]¶

7.18. Frog.second_part module¶

Frog.second_part.how_many_QM_jobs_are_left(GP)[source]¶

Find how many QM calculations has to be done.

Either starting from a first part: No QM calculation that should be done had been done. Hence just count them. Either starting from a restart Frog run: a previous set of QM calculation may have been done. So we have to check how many QM calcualtion have been done compared to the previous run.

Frog.second_part.prepare_submission_scripts(GP, L_QM_todo, L_nbr_job_todo)[source]¶: Prepare the submission scripts to be run on a cluster. First assignes how many QM calculation should be done on a servor of each MT, then creates the scripts using or not the job array technic.

7.19. Frog.third_part module¶

Frog.third_part.load_qm_results_one_frame(GP, time_step)[source]¶: TODO

Frog.third_part.perform_effective_field_one_frame(GP, time_step)[source]¶: TODO

Frog.third_part.perform_effective_field_one_frame_old(GP, time_step)[source]¶: TODO

Frog.third_part.run_third_part(time_step_management, L_dict)[source]¶: TODO

7.20. Frog.toolbox module¶

Frog.toolbox.all_possible_frequency_caligraphy(frequency)[source]¶

Frog.toolbox.binarize_array(L, nbr_bits, y_min, y_max, pbc=False)[source]¶: TODO

Frog.toolbox.change_tuple_component(mytuple, component_to_change, newvalue)[source]¶: Return a new tuple with one component changed.

Frog.toolbox.concatenate_bin(bin_one, bin_two)[source]¶: Add safely a new dimension to the bin_size.

Frog.toolbox.concatenate_path(left, right, left_unable=False, right_unable=False, unable_return=False)[source]¶

Concatenate the string “left” to the string “right” assuming that they are separated by an ‘/’. This function was written to avoid trouble while directory-name concatenation – due to bad input in the input file or to lighten the writing of the code/avoid implementation mistakes.

If left_unable is set, it has to be a string, it will avoid concatenation of the left and right argument if left==left_unable. In this case, the function will return either the left or the right argument. This is set by defining unable_return to the string “left” or “right”.

right_unable option works similarly, the condition is on the right argument.

unable_return should be equal to the string “left” or “right” if the option left_unable and/or right_unable are set.

Frog.toolbox.creat_beta_intrinsic(L_Beta)[source]¶: Return the molecular beta using intrasinc symmetry for SHG! 2w = w + w. 18 independant component: [Bxxx, Bxyy, Bxzz, Bxxy, Bxxz, Bxyz, Byxx, Byyy, Byzz, Byxy, Byxz, Byyz, Bzxx, Bzyy, Bzzz, Bzxy, Bzxz, Bzyz] are expected as input.

Frog.toolbox.creat_beta_kleinman(L_Beta)[source]¶: Return the molecular beta using Kleinman symmetry from the 10 independant component: Bxxx, Byyy, BzzzBxyy, Bxzz, Byxx, Byzz, Bzxx, Bzyy, Bxyz. The understood input is: L_beta = [Bxxx, Byyy, Bzzz, Bxyy, Bxzz, Byxx, Byzz, Bzxx, Bzyy, Bxyz].

Frog.toolbox.creat_directory(directory)[source]¶: Creat the directory given in the argument. Works also if several directory have to be created. The implmentation may be smater but this old version works. Do not hesitate to change it if you like.

Frog.toolbox.creat_name_for_MT_module_load(name_module)[source]¶

Return a string with the full path to load the MT module.

Today, the path is: Source_code/Molecules/the_file.py

Note: This function has been made in case the global architecture of Frog changes.

Frog.toolbox.delete_file(name_file, directory='')[source]¶: Delete the file if it exists.

Frog.toolbox.diff_time(time_i, time_f)[source]¶

Return the time spend between the time_i and time_f call. These time should have been generated using time.time() function.

The first return delta_t simply gives the time spend in sec. The delta_t_string return a string with present the time spend in the year, month, days, hour, min, sec format.

Frog.toolbox.extract_file_name(filename)[source]¶: Extract the filename if the input is given as a general path.

Frog.toolbox.frog_format_time(the_time)[source]¶: Return the time in year-month-days h:m:s format. Use as input time.struct_time object.

Frog.toolbox.module_binarized_array(x, y_min, y_max, pbc=False)[source]¶

Frog.toolbox.open_pickle(name_pickle, directory='')[source]¶: Open a pickle and return the value. The pickle is close anyway. The ‘directory’ option can be used to update the name of the pickle file. In this case: name_pickle = directory + name_pickle. This option have been made to lighten the implementation of some part of the code.

Frog.toolbox.parallelize_fct(GP, function_to_launch, L_dict)[source]¶: TODO

Frog.toolbox.return_time()[source]¶: Return the current time using the Frog time format (year-month-days h:m:s).

Frog.toolbox.rotate_1st_order_tensor(base_changement, vector)[source]¶: This function transform a 1st order tensor (3d vector) from one base to another using a rotational matrix called base_changement. In Frog, the matrix are defined to be: vector_{mol} = base_changement . vector_{lab} Then: vector_{lab} = rotate_1st_order_tensor(base_changement.T, vector_{mol}) Then: vector_{mol} = rotate_1st_order_tensor(base_changement, vector_{lab})

Frog.toolbox.rotate_2nd_order_tensor(base_changement, tensor)[source]¶

This function transform a 2nd order tensor (3X3 matrix) from one base to another using a rotational matrix called base_changement. In Frog, the matrix are defined to be: vector_{mol} = base_changement . vector_{lab} Then: tensor_{lab} = rotate_2nd_order_tensor(base_changement, tensor_{mol}) Then: tensor_{mol} = rotate_2nd_order_tensor(base_changement.T, tensor_{lab})

For electric field gradients If one have dEidxj in the laboratory frame, with the base_changement matrix (R) is defined to be: vector_{lab} = base_changement . vector_{mol}. Then, to go in the molecular frame:

dEadxb_{mol} = sum_{i,k} R_{ia} R_{kb} dEidxk_{lab}

In pratice: dE_{mol} = rotate_2nd_order_tensor(base_changement.T, dE_{lab})

Frog.toolbox.rotate_3rd_order_tensor(base_changement, tensor)[source]¶: ‘ This function transform a 3rd order tensor (3X3X3 matrix) from one base to another using a rotational matrix called base_changement. In Frog, the matrix are defined to be: vector_{mol} = base_changement . vector_{lab} Then: tensor_{lab} = rotate_3nd_order_tensor(base_changement, tensor_{mol}) Then: tensor_{mol} = rotate_3nd_order_tensor(base_changement.T, tensor_{lab})

Frog.toolbox.rotate_4th_order_tensor(base_changement, tensor)[source]¶: ‘ This function transform a 4th order tensor (3X3X3X3 matrix) from one base to another using a rotational matrix called base_changement. In Frog, the matrix are defined to be: vector_{mol} = base_changement . vector_{lab} Then: tensor_{lab} = rotate_4th_order_tensor(base_changement, tensor_{mol}) Then: tensor_{mol} = rotate_4th_order_tensor(base_changement.T, tensor_{lab})

Frog.toolbox.save_pickle(name_save, data_to_save, text=False, directory='')[source]¶: Save something inside a pickle and make sure the name of the pickle is a ‘.p’. The ‘text’ optional argument can be used to print a message after saving the data. The ‘directory’ option can be used to update the name of the pickle file. In this case: name_save = directory + name_save. This option have been made to lighten the implementation of some part of the code.

Frog.toolbox.write_xyz_mol(nbr_atom, L_atom_type_name, L_pos, name_file, type_writting='a')[source]¶: TODO

7.21. Frog.universe_manager module¶

Frog.universe_manager.QM_preparation_PE_and_PE_plus_QMBox(GP, u, ts, pbc, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype, L_target_mean_pos, pos_mol_target, QM_file_localization_name)[source]¶

Frog.universe_manager.QM_preparation_PE_long(GP, u, ts, L_box_size, molecule_type_module, moleculetype, sdparameter, name_attr, kkk, time, L_moleculetype, L_target_mean_pos, pos_mol_target, QM_file_localization_name)[source]¶

Frog.universe_manager.built_environment_first_shell_number(residue_nbr, max_distance, GP, u, ts, L_name_partner)[source]¶: TODO

Frog.universe_manager.centering_position_neighbourg(L_pos_neigh, mean_position, max_distance, smparameter, box_size)[source]¶

Frog.universe_manager.centering_position_neighbourg_old(L_pos_neigh, mean_position, max_distance, neigh_size_max, box_size)[source]¶

Frog.universe_manager.closest_idx(lst, K)[source]¶

Frog.universe_manager.construct_pbc_movement(env_authorised_pbc_condition, L_box_size)[source]¶: Construct the list of the possible movement (to increase the sample size) according to the PBC condition and the authorised direction. Note that this function have to be called for every time step since the box size may vary in time.

Frog.universe_manager.environement_builder_return_position(residue_nbr, mean_position, target_molecule_type_module, max_distance, GP, u, ts, pbc, L_name_partner=False, just_number_mol=False)[source]¶

Return the position centered around the molecule number ‘’residue_nbr’’ up to a distance ‘’max_distance’’. This is done in 2 steps:: First find the ‘’first shell’’ of neighbors number up to the max_distance. This uses the PBC condition in all the direction. Check that these neighbors are allowed using the specific PBC restriction. Then, duplicate them using the PBC condition if needed. The output is the position of the neigbors in the target molecule frame.

Frog.universe_manager.pbc_condition_neigh(pos_ref, pos_tomove, max_norm, L_pbc_parameter)[source]¶

Frog.universe_manager.recurcive_pbc_movement_constructor(movement_to_try, L_movement)[source]¶

Frog.universe_manager.single_neighbour_find_position_PBC(residue_nbr, mean_position, res_neigh, L_pos_neigh, L_pos_neigh_mean, smparameter, max_distance, GP, L_movement)[source]¶

Frog.universe_manager.single_neighbour_return_position(residue_nbr, mean_position, res_neigh, module_neigh_temp, smparameter, max_distance, GP, u, ts, pbc)[source]¶

Frog.universe_manager.trajectory_load(GP, time_step, try_cut_traj=True)[source]¶: TODO

Frog.universe_manager.trajectory_load_old(GP, time_step, try_cut_traj=True)[source]¶: TODO

Frog.universe_manager.trajectory_selection_for_residues(GP, L_key_mol)[source]¶: Return the number of the first and last atom of the residue selection.

7. Frog package¶

7.1. Subpackages¶

7.2. Submodules¶

7.3. Frog.check module¶

7.4. Frog.class_DiagramParameter module¶

7.5. Frog.class_Diagrams module¶

7.6. Frog.class_Molecule module¶

7.7. Frog.class_OpticalParameter module¶

7.8. Frog.class_modules module¶

7.9. Frog.dalton_manager_module module¶

7.10. Frog.electric_field_module module¶

7.11. Frog.error_messages module¶

7.12. Frog.first_part module¶

7.13. Frog.frog_class module¶

7.14. Frog.frog_data_analysis module¶

7.15. Frog.geometry_manager module¶

7.16. Frog.main module¶

7.17. Frog.messages module¶

7.18. Frog.second_part module¶

7.19. Frog.third_part module¶

7.20. Frog.toolbox module¶

7.21. Frog.universe_manager module¶

7.22. Module contents¶

Navigation