UtilityPackage

Utility function package:

• UtilityPackage.npz_unilen(npz, n_pts, masked=True, filled=0)
  Unifying the length of the input numpy npz package. For a package of multi-dimensional arrays, the "length" refers to the first dimension.

  • Parameters:
    • npz: numpy npz, numpy array, python list
      first argument. Input array.
    • n_pts: integer
      second argument. Target length to unify to.
    • masked: optional, bool, default=True
      if true, makes masked arrays instead of regular ones.
    • filled: optional, any type, default=0
      when the original array has less elements than the array with target length, fill in the missing
      spots with value passed in via this parameter.
  • Returns: a numpy (masked/regular) array.

• UtilityPackage.expand_multi_dims(a_shape, array, n_axis)
  Adds singleton dimensions to an array to have the same number of dimensions as a multi-dimensional numpy array for convenient broadcasting.

  • Parameters:
    • a_shape: tuple
      first argument. Shape of the target multi-dimensional array.
    • array: 1-D numpy array, python list
      second argument. Input array.
    • n_axis: integer.
      third argument. The number of axis on which to put the input array. a_shape[n_axis] must be the same as len(array), or an error will be raised.
  • Returns: a numpy array.
  • Examples:
    a[2,3,4,5] is to be multiplied by b[4]. Directly doing so with a*b would yield an error due to numpy not knowing which axis (axes) to broadcast along. UtilityPackage.expand_multi_dims((2,3,4,5), b, 3) returns b[1,1,4,1]. a[2,3,4,5]*b[1,1,4,1] can now be executed by numpy.

• UtilityPackage.maxpts_from_npz(npz_file, axis=0)
  Obtain the maximum length of arrays among a numpy npz package.

  • Parameters:
    • npz_file: numpy npz package
      first argument. Input array. Its arguments have to be the default ones, e.g. "arr_0", "arr_1", ...
    • axis: integer
      optional, default=0. Which axis to be looking at in the case of multi-dimensional arrays in the numpy npz package.
  • Returns: an integer.

• UtilityPackage.rep_pinpoint(array, pinpoint, diss=None)
  This method selects representing points along a trajectory based on pinpoint array and optionally on diss array (dissociation detection results array). When diss is not passed in, pinpoint array should have same form as diss normally would, namely, a n_channel by n_trajectory matrix where -1 marks non-dissociation trajectories and any integer other than -1 signifies the number of point to be taken as representative of such trajectory. Note: the input array has to have the first two dimensions corresponding to trajectories and points along trajectory.

  • Parameters:
    • array: numpy array
      first argument. Input array to have its elements selected based on pinpoint array and/or diss array.
    • pinpoint: numpy array
      second argument. Dimension of this array should be pinpoint[channel, trj], where channel is the number of dissociation channels, and trj is the number of trajectories overall. The value in this array is either -1, signifying that trajectroy should not be selected in that channel, or any integer >= 0, signifying which point to take as the representing point along that trajectory.
    • diss: numpy array
      optional, default=None. Dimension of this array is the same as poinpoint array, diss[channel, trj]. The value in this array is similar to that of poinpoint array, that is either -1, signifying that trajectroy did not dissociate in that channel, or any integer >= 0, signifying at which point the trajectory dissociated. Passing in an array that is not None will make this method select trajectory based on diss array, instead of pinpoint array. But the points along each of those trajectories will still be selected based on pinpoint array.
  • Returns: a list of numpy arrays.

• UtilityPackage.cts2xyz(cts_npz, atom_list, convert_factor=1.889725989)
  Convert a Cartesian coordinate numpy npz package into a list of string that constitute a .xyz file.

  • Parameters:
    • cts_npz: numpy npz package
      first argument. The input numpy npz package.
    • atom_list: python list, numpy array of strings
      second argument. This list contains the atomic symbols of the molecule.
    • convert_factor: float
      optional, default=1.889725989. This is the unit conversion factor. The default is to convert Bohr to angstrom.
  • Returns: a list of strings.

• UtilityPackage.regulate_data(data, threshold_reg, axis_time=0)
  Regulate the data so that the absolute of the values above a certain threshold along a certain axis can be discarded.

  • Parameters:
    • data: numpy array
      first argument. Input array.
    • threshold_reg: float, integer, positive
      second argument. The value of threshold.
    • axis_time: integer
      optional, default=0. The number of axis corresponding to time in the case of trajectory analysis. If at any points along this axis the absolute of the value is larger than threshold_reg, the entire trajectory (the whole axis) is skipped, i.e. discarded.
  • Returns: a list of trajectory numbers that passed the test.