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.