finesse.utilities.misc module
Miscellaneous utility functions for any part of Finesse.
- finesse.utilities.misc.calltracker(func)[source]
Decorator used for keeping track of whether the current state is inside the decorated function or not.
Sets an attribute has_been_called on the function which gets switched on when the function is being executed and switched off after the function has returned. This allows you to query
func.has_been_calledfor determining whether the code being executed has been called from within func.
- finesse.utilities.misc.check_name(name)[source]
Checks the validity of a component or node name.
A name is valid if it contains only alphanumeric characters and underscores, and is not empty.
Parameters
- namestr
The name to check.
Returns
- namestr
The name passed to this function if valid.
Raises
- ValueError
If name contains non-alphanumeric / underscore characters.
- finesse.utilities.misc.doc_element_parameter_table(cls)[source]
Prints table for a particular element class.
- finesse.utilities.misc.find(x, value)[source]
Finds value in the list x and returns its index, returning None if value is not in the list.
- finesse.utilities.misc.graph_layouts()[source]
Available NetworkX and graphviz (if installed) graph plotting layouts.
- finesse.utilities.misc.inheritors(klass: type) set[type][source]
Returns all classes that inherit from
klassParameters
- klasstype
Class to get inheritors from
Returns
- set[type]
set of classes that are a subclass of
klass
- finesse.utilities.misc.is_iterable(obj)[source]
Reliable check for whether an object is iterable.
Note that strings are treated as non-iterable objects when performing this check. This will only return true for iterable non-str objects.
Returns
- flagbool
True if obj is iterable, False otherwise.
- finesse.utilities.misc.opened_file(filename, mode)[source]
Get an open file regardless of whether a string or an already open file is passed.
Adapted from
numpy.loadtxt().Parameters
- filenamestr,
pathlib.Path, or file-like The path or file object to ensure is open. If filename is an already open file object, it is yielded as-is, and is not closed after the wrapped context exits. If filename is a string, it is opened with the specified mode and yielded, then closed once the wrapped context exits.
- modestr
The mode to open filename with, if it is not already open.
Yields
io.FileIOThe open file with the specified mode.
Notes
If filename is an open file, mode is ignored; it is the responsibility of the calling code to check that it is opened with the correct mode.
- filenamestr,
- finesse.utilities.misc.pairwise(iterable)[source]
Iterates through each pair in a iterable.
Parameters
- iterable
collections.abc.Iterable An iterable object.
Returns
- zip
A zip object whose .next() method returns a tuple where the i-th element comes from the i-th iterable argument.
- iterable
- finesse.utilities.misc.reduce_getattr(obj, key: str, delimiter: str = '.')[source]
Applies a nested getattr with reduce to select an attribute of a nested object within obj.
Parameters
- objobject
Object to search
- keystr
Delimited string of attributes
- delimiterstr, optional
Delimiter character of key
Returns
Attribute of object
- finesse.utilities.misc.track_particles(frames: ndarray, vectors: array = None, *, position_weight: float = 1.0, velocity_weight: float = 0.5, vector_weight: float = 0.5) Tuple[ndarray, ndarray][source]
Track particles across a sequence of frames using a weighted combination of position, velocity, and optional vector information.
Parameters
- framesnp.ndarray
A 3D array of shape (num_frames, num_particles, num_dimensions) containing the positions of particles in each frame.
- vectorsnp.array, optional
A 3D array of shape (num_frames, num_particles, vector_dimensions) containing additional vector information for each particle.
- position_weightfloat, optional
Weight for the position cost in the cost matrix. Default is 1.0.
- velocity_weightfloat, optional
Weight for the velocity cost in the cost matrix. Default is 0.5.
- vector_weightfloat, optional
Weight for the vector cost in the cost matrix. Default is 0.5.
Returns
- tracked_positionsnp.ndarray
A 3D array of shape (num_frames, num_particles, num_dimensions) containing the tracked positions of particles.
- indiciesnp.ndarray
A 2D array of shape (num_frames, num_particles) containing the indices of the tracked particles.
Notes
The algorithm initializes the velocities of particles to zero and iteratively updates their positions and velocities based on the weighted combination of position, velocity, and optional vector information. The cost matrix is computed using the Euclidean distance between predicted and current positions, observed velocities, and vector information is weight by 1-dot(v1,v2). The assignment problem is solved using the Hungarian algorithm (linear_sum_assignment) to find the optimal assignment of particles between frames.
This is implementation will not work with noisy data and will confuse points if the steps are too large. Experimenting with the weightings may be necessary if you see jumps in the tracking.
This implementation was originally written to track the evolution of eigenmodes as eigenvalues and eigenvectors are not sorted in any particular way.