5.4. Diagram Structure

5.4.1. Reminder about data structure

Please see the MT structure page to be aware of how the analysis are stored in ||frog|.

In short, an MT contains all the information regarding a set of molecule at a given MD frame. There are as many MT object as time step and molecule type declared.

It contains all the parameters needed to performed the analysis, which does not depend on the time step, in the Molecule Type Parameter object.

It contains a list of all the molecule: every molecule is described using a singlemolecule object. In this Single Molecule object, all the individual property which should be computed are stored: the mean position, the number of H-bond, the hyperpolarizability… In the analysis available page, is presented what singlemolecule attribute is generated for each analysis required. For instance, asking for a ‘beta’ analysis will create for each singlemolecule object an attribute ‘beta’ where the individual beta value will be stored for each time step.

Finaly, the MT object contains the diagram corresponding to the analysis done for this molecule set. There are at least as many diagram as analysis performed.

5.4.2. The diagram structure

Every analysis declared refers to a class, which inherite from the Diagram class. This diagram class defines the attributes presented bellow as well as basic function. Every analysis defines how to deal with the user-input, how to compute the individual quantity, how to add an individual quantity to the distribution… These informations relative to the analysis are presented in this page.

Every diagram are attached to a Single Diagram Parameter object, contained in the myMT.mtparameter.dparamter.L_diagram list. This object contains the parameter needed for the analysis and the discretization. This idea is that the sdparameter contains most of the time-invariant parameters for the diagram, while the diagram itself contains the time-dependant values – i.e. the results for every time step.

Note

The diagram are directly stored in the MT object. Therefore, to call a diagram, you may want to look at the sdparamter first. To call the diagram relative to the sdparameter, use: getattr(myMT, sdparameter.name)

Here is what contains every diagram, due to the Diagram class inheritance:

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

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

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

Diagram.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, 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].

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

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

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

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

Diagram.unit

Type [unit]

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

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

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

5.4.3. Diagram Parameter

The dparameter attribute is a Diagram Parameter object. It is contained in the mtparameter (which is a Molecule Type Parameter object) attribute of the Molecule Type Object. In Short: myMT.mtparameter.dparameter.

It is built when the diagram input are set by the user using the function myMT.read_diagram_input, see this page for pratical examples. It contains information about the analysis and diagram required for this MT.

Note

If ‘optical’ analysis are required, the parameters relative to these analysis are completed by the one provided in the Optcial Parameter object: myMT.mtparameter.optparameter.

Here are the available attribute of this object. Please note that you have no use to call or add them manually for a standard use of . This part is intented for advance user.

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

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

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

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

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

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

5.4.4. Single Diagram Parameter

All the single parameter object are contained in the myMT.mtparameter.dparameter.L_diagram list. See above for the dparameter object.

They are built when the diagram input are set by the user using the function myMT.read_diagram_input, see this page for pratical examples. Each sdparameter objects are attached to a diagram. The attributes of these sdparameter depend on the analysis required. In the list of the available analysis is details which sdparameter attributed are added for each analysis.

Note

If ‘optical’ analysis are required, the parameters relative to these analysis are completed by the one provided in the Optcial Parameter object: myMT.mtparameter.optparameter.

Here are the available attribute of this object. Please note that you have no use to call or add them manually for a standard use of . This part is intented for advance user.

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

SingleDiagramParameter.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’.

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

Note

See this page for more informations about the geometrical discretization of diagram.

SingleDiagramParameter.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…

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

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

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