DissociationDetect

This is a dissociation detection module based on distance matrix.

• Initialization: DissociationDetect(cts_raw, channel_def, frag_gen=False, frag_identifier="Channel", frag_break_factor=1.5, frag_remain_factor=1.5, frag_delim=";", frag_precision=2, cts_unit="Bohr", value_unit="Angstrom", atom_axis=1, dist_mat=None, whitelist=None, diss=None)

  • Parameters:

    • cts_raw: numpy npz package, numpy array, python list
      first argument. The Cartesian coordinates.

    • channel_def: string.
      second argument. The definition of dissociation channels. This consists of lines of simple logic rules in the following format:

                [atom number 1]-[atom number 2] >(or <) [value 1]; [atom number 3]-[atom number 4] >(or <)
                [value 2]; ... or [atom number 5]-[atom number 6] >(or <) [value 3];
                [atom number 7]-[atom number 8] >(or <) [value 4]; ... or ...
      
                The conditions separated by ";" (can be customized by parameter later on) will be joined by
                logical and, and the resulted conditions separated by "or" (cannot be customized) will then be
                joined by logical or.
      
                The following is an example:
      
                    2-1 > 1.65;5-1 < 2.70 or 8-5 > 1.65;5-1 < 2.70
      
                This means the following condition: (bond between atom 1 and atom 2 is larger than 1.65 and
                bond between atom 5 and 1 is smaller than 2.7) or (bond between atom 8 and atom 5 is larger
                than 1.65 and bond between atom 5 and 1 is smaller than 2.7).
                Each line corresponds to a single dissociation channel.
      

    • frag_gen: bool
      optional, default=False. Flag to switch on treating channel_def as input string for FragGen() object which takes in molecular and fragment connectivity definitions and generate dissociation channel definitions to use. See documentation of FragGen class.

    • frag_identifier="Channel", frag_break_factor=1.5, frag_remain_factor=1.5, frag_delim=";", frag_precision=2:
      these optional parameters are used in FragGen() object. See documentation of FragGen class for their usage.

    • cts_unit: string
      optional, default="Bohr". Unit of input Cartesian coordinates.

    • value_unit: string
      optional, default="Angstrom". Unit of channel definition values are in. A conversion factor will be generated based on these two optional parameters.

    • atom_axis: integer
      optional, default=1. The number of axis the atoms of the molecule is on. The expected Cartesian coordinates array, cts_raw has the following dimensions: cts_raw[trj, points, atoms, xyz]. Since cts_raw is treated as a list of arrays, each array has the dimensionality of cts_1trj[points, atoms, xyz]. Its 1th axis corresponds to atoms of the molecule.

    • dist_mat: python list of numpy arrays
      optional, default=None, which signifies calculating distance matrix during initialization. Distance matrix which the whole module is based on.

    • whitelist: python list of numpy arrays
      optional, default=None. Optional white list (see TrjScreen.ejump_whitelist() method for its form and usage) for skipping any points along the trajectory that are not on this white list.

    • diss: numpy array
      optional, default=None. This is the result of the main function, dissociation detection, of this class. But since there are some additional methods, e.g. DissociationDetect.pinpoint_gen(), DissociationDetect.frag_detect(), that need this as input. This dissociation detection array can be passed in to skip the dissociation detection procedure and these additional methods can be used directly.

  • Note: besides the two positional, i.e. mandatory, arguments, cts_raw and channel_def, only frag_gen and its related optional arguments are needed in most cases.

• DissociationDetect.dissociation_detect(whitelist=None, recombination=True)
  This method execute the main function of this class: dissociation detection based on the logic defined by rule strings.

  • Parameters:
    • whitelist: python list of numpy arrays
      optional, default=None. Optional white list (see TrjScreen.ejump_whitelist() method for its form and usage) for skipping any points along the trajectory that are not on this white list, similar to its usage during initialization.
    • recombination: bool
      optional, default=True. Flag for considering recombination. If turned on, the trajectory whose geometry satisfying dissociation definition at one point can be marked as "non-dissociating" if such condition is broken later on. In other words, this implies the dissociation condition was met and kept until the very last time step.
  • Returns: numpy array[channel, trj]. Each element is either -1, marking "non-dissociating", or a positive integer, which is the number of time step the dissociation first occured.

• DissociationDetect.pinpoint_gen(trj_whitelist=None, length_laser=374, search_flag=1, diss=None, non_diss_filler=False, default_filler=-1)
  This method pinpoint a single time step among "valid points" along a trajectory to represent the whole trajectory for each trajectory in each dissociation channel.
  "Valid points": a point, i.e. a time step, is called a "valid point" when it is on the white list, (more specifically, at which point the corresponding element in white list array equals to True), after laser pulse if possible (this condition will be ignored if trajectory finished before the end of laser pulse), and after the dissociation (determined by diss array) if the trajectory was marked as "dissociated".

  • Parameters:
    • trj_whitelist: python list of numpy arrays
      optional, default=None. Optional white list (see TrjScreen.ejump_whitelist() method for its form and usage) for skipping any points along the trajectory that are not on this white list, similar to its usage during initialization.
    • length_laser: positive integer
      optional, default=374. The number of points, i.e. time steps, of the laser pulse duration.
    • search_flag: integer
      optional, default=1. When set to 1, the algorithm takes the first point among "valid points"; when set to anything else, it takes the last point among "valid points".
    • non_diss_filler: bool
      optional, default=False. When set to True, in the case of the trajectory being marked as "non-dissociating", the algorithm takes first or last point among "valid points" (determined by search_flag parameter) as a filler; otherwise, in the case of the trajectory being marked as "non-dissociating", the algorithm takes whatever the default_filler parameter sets to as a filler.
    • default_filler: integer
      optional, default=-1. As mentioned previously, this is the default filler for the case of the trajectory being marked as "non-dissociating". The default value, -1, makes the pinpoint array behave very similar to diss array, since in both cases, -1 signifies "non-dissociating", any other value is a representing time step along the trajectory.
    • diss: numpy array
      optional, default=None. If not passed in, the diss array stored in DissociationDetect.diss attribute during previous usage of DissociationDetect.dissociation_detect() will be taken. This parameter is to make it possible to read in a different diss array as what was generated by DissociationDetect.dissociation_detect() or previous runs of the entire program.
  • Returns: numpy array in a similar form as diss array, which is a result of DissociationDetect.dissociation_detect() method. The dimensionality of it is pinpoint[channel, trj].

• DissociationDetect.frag_detect(pinpoint=None)
  This method is built upon FragGen class to determine which one of the possible combinations were picked up by dissociation_detect() at a certain point (determined by either pinpoint array or diss array) along each trajectory and for each dissociation channel.

  • Parameters:
    • pinpoint: numpy array
      optional, default=None. The result of DissociationDetect.pinpoint_gen() method, which pinpoint a single time step among "valid points" along a trajectory to represent the whole trajectory for each trajectory in each dissociation channel. See DissociationDetect.pinpoint_gen() for the detailed documentation of this array. If nothing passed in, the diss array generated by previous method for the same instance of DissociationDetect class will be taken when determine which point along a trajectory to be looking at.
  • Returns: python list of lists of tuples. The tuples contains fragmentation definition in terms of atomic number.

• Example:
  Suppose a Cartesian coordinates array has been read and saved by class MassRead. Read this array into cts_raw. And suppose a text file, rule_string.txt, was written containing a few lines of geometry conditions as rule string, in similar form as the example mentioned above:

    2-1 > 1.65;5-1 < 2.70 or 8-5 > 1.65;5-1 < 2.70
  

  The following script would yield a dissociation array and a representing point array:

    with open("rule_string.txt", "r") as fh:
        rules = fh.read()
    detector = DissociationDetect(cts_raw, rules)
    diss = detector.dissociation_detect()
    pinpoint = detector.pinpoint_gen()
    # Now print out the channel number and all the trajectories dissociated in this channel as well as the
    representing points.
    for i, i_diss_pp in enumerate(zip(diss,pinpoint)):
        i_diss, i_pp = i_diss_pp
        print("Channel "+str(i)+": ")
        print(" ".join([np.where(i_diss!=-1)[0]]))
        print("at points: "+" ".join([i_pp[np.where(i_diss!=-1)[0]]]))