Reference¶

This is the reference for the classes and functions defined in the nodefinder module.

Search¶

Run function¶

Submodule for searching the nodal features given a gap function. The result is given as a “point-cloud” of nodes.

async nodefinder.search.run_async(gap_fct, *, limits=((0, 1), (0, 1), (0, 1)), periodic=True, initial_state=None, save_file=None, save_delay=5.0, load=False, load_quiet=True, initial_mesh_size=10, force_initial_mesh=False, refinement_stencil='auto', gap_threshold=1e-06, feature_size=0.002, use_fake_potential=False, nelder_mead_kwargs=mappingproxy({}), num_minimize_parallel=50, recheck_pos_dist=True, recheck_count_cutoff=0, simplex_check_cutoff=0)[source]¶

Run the nodal point search.

Parameters

gap_fct (collections.abc.Callable) – Function or coroutine describing the potential of which nodes should be found.
limits (tuple(tuple(float))) – The limits of the box where nodes are searched, given as tuple for each dimension.
periodic (bool) – Indicates whether periodic boundary conditions are used for the coordinate system.
save_file (str) – Path to the file where the intermediate results are stored.
save_delay (float) – Minimum delay (in seconds) between saving the results.
load (bool) – Enable or disable loading the initial state from save_file.
load_quiet (bool) – When set to True, ignore errors when loading the initial state.
initial_mesh_size (int or tuple(int)) – Size of the initial mesh of starting points. Can be given either as a single integer or as a list of integers corresponding to the different dimensions.
force_initial_mesh (bool) – If True, add the initial mesh also when restarting the calculation from an intermediate result.
refinement_stencil (np.array) – The stencil of simplices used in the refinement. Normalized such that the starting point is at the origin, and the dist_cutoff is one. The array must have dimensions (N, dim + 1, dim), where dim is the dimension of the problem, and N can be chosen to be the number of refinement minimization runs.
gap_threshold (float) – Threshold for the function value for which a given point is considered to be a node.
feature_size (float) – Threshold for the distance between two nodes where they are considered distinct.
use_fake_potential (bool) – If True, the minimization for a given simplex is performed in two steps, first adding a fake potential to repel the minimization from existing nodes.
nelder_mead_kwargs (collections.abc.Mapping) – Keyword arguments passed to the Nelder-Mead algorithm.
num_minimize_parallel (int) – Maximum number of minimization calculations which are launched in parallel.
recheck_pos_dist (bool) – Indicates whether the position of a refinement box is checked again before launching the corresponding refinement.
recheck_count_cutoff (int) – Number of positions which are allowed to be within the cutoff distance when re-checking the position.
simplex_check_cutoff (int) – Number of vertices which are allowed to be within the cutoff distance when re-checking the simplex.

Returns

The result of the search algorithm.

Return type

SearchResultContainer

nodefinder.search.run(*args, **kwargs)[source]¶

Wrapper around run_async() that runs the node search synchronously.

Parameters

args (tuple) – Positional arguments passed to run_async().
kwargs (collections.abc.Mapping) – Keyword arguments passed to run_async().

Result classes¶

Submodule defining the result classes of the search step.

class nodefinder.search.result.JoinedMinimizationResult(*, child, ancestor)[source]¶

Wrapper for minimization results that result from two steps.

ancestor¶

Result of the first minimization run.

Type: MinimizationResult

child¶

Result of the second minimization run.

Type: MinimizationResult

classmethod from_hdf5(hdf5_handle)¶: Deserializes the object stored in HDF5 format.

class nodefinder.search.result.MinimizationResult[source]¶

Represents the optimization result.

pos¶

The solution of the optimization.

Type: ndarray

value¶

Value of objective function.

Type: ndarray

success¶

Whether or not the optimizer exited successfully.

Type: bool

status¶

Termination status of the optimizer. Its value depends on the underlying solver. Refer to message for details.

Type: int

message¶

Description of the cause of the termination.

Type: str

num_fev¶

Number of evaluations of the objective functions.

Type: int

num_iter¶

Number of iterations performed by the optimizer.

Type: int

simplex_history¶

History of simplex values.

Type: ndarray, optional

fun_simplex_history¶

History of function values of the simplex.

Type: ndarray, optional

classmethod from_hdf5(hdf5_handle)[source]¶: Deserializes the object stored in HDF5 format.

to_hdf5(hdf5_handle)[source]¶: Serializes the object to HDF5 format, attaching it to the given HDF5 handle (might be a HDF5 File or Dataset).

class nodefinder.search.result.SearchResultContainer(*, coordinate_system, minimization_results=(), gap_threshold, dist_cutoff, refined_results=())[source]¶

Container for the results of a search run.

coordinate_system¶

Coordinate system used.

Type: CoordinateSystem

nodes¶

Minimization results which fulfill the gap threshold criterion.

Type: list(MinimizationResult)

gap_threshold¶

Threshold for results to be considered a node.

Type: float

dist_cutoff¶

Cutoff distance for searching neighbouring nodes.

Type: float

add_result(res)[source]¶

Add a minimization result to the container.

Parameters: res (MinimizationResult) – Minimization result to add.

classmethod from_hdf5(hdf5_handle)¶: Deserializes the object stored in HDF5 format.

get_all_neighbour_distances(pos)[source]¶

Calculate the distances to neighbouring nodes from a given position. Only neighbours within dist_cutoff are taken into account.

Parameters: pos (numpy.ndarray) – Position for which to calculate the distances.

get_neighbour_distance_iterator(pos)[source]¶

Returns an iterator over the distance to neighbouring nodes from a given position. Only neighbours within dist_cutoff are taken into account.

Parameters: pos (numpy.ndarray) – Position for which to calculate the distances.

get_refined_neighbour_distance_iterator(pos)[source]¶

Returns an iterator over the distance to neighboring nodes which have been used as a starting point in a refinement procedure.

Parameters: pos (numpy.ndarray) – Position for which to calculate the distances.

property minimization_results¶: list(MinimizationResult): All minimization results, including rejected points.

set_refined(pos)[source]¶

Set a position to be refined.

Parameters: pos (np.array) – The position from where refinement started.

class nodefinder.search.result.ControllerState(*, result, simplex_queue, position_queue)[source]¶

Container class for the current result and queue of the search.run() function.

classmethod from_hdf5(hdf5_handle)¶: Deserializes the object stored in HDF5 format.

Plotting¶

Defines functions for plotting the results of the search step.

nodefinder.search.plot.points(result, *, axis=None)[source]¶

Plot the nodal points of a given result.

Parameters

result (SearchResultContainer) – Result whose nodal points should be plotted.
axis (matplotlib.axes.Axes, optional) – Axes on which the points should be plotted.

nodefinder.search.plot.simplices(result, *, nodes=(), axis=None, line_settings=mappingproxy({'color': 'C0'}))[source]¶

Plot the simplices used in the minimization for a given node.

Parameters

result (SearchResultContainer) – Result of the search step.
nodes (list(MinimizationResult)) – Nodes for which the simplex history should be plotted.
axis (matplotlib.axes.Axes, optional) – Axes on which the points should be plotted.
line_settings (dict) – Keyword arguments passed to matplotlib.axes.Axes.plot().

nodefinder.search.plot.stencil(stcl, *, axis=None, line_settings=mappingproxy({'color': 'C0'}), origin_settings=mappingproxy({'color': 'C1'}), plot_sphere=True, sphere_settings=mappingproxy({'color': 'C2', 'alpha': 0.2}))[source]¶: Plot a refinement stencil.

Identify¶

Run function¶

Submodule for identifying nodal features such as points and lines from a point-cloud of nodes as created by the search submodule.

nodefinder.identify.run(result, feature_size=None, evaluate_line_method='ballistic')[source]¶

Identify the nodal clusters from a search.run() result.

Parameters

result (SearchResultContainer) – Result of the search step.
feature_size (float, optional) – Distance between two nodal points at which they are considered distinct. Uses the feature_size used in the search step by default.

nodefinder.identify.run_from_positions(positions, *, coordinate_system, feature_size, evaluate_line_method='shortest_path')[source]¶

Identify the nodal clusters from a list of positions.

Parameters

positions (list(tuple(float))) – The list of nodal positions.
coordinate_system (CoordinateSystem) – Coordinate system used to calculate distances.
feature_size (float) – Distance between two nodal points at which they are considered distinct.

Result classes¶

Define the result classes for the identification step.

class nodefinder.identify.result.IdentificationResultContainer(*, coordinate_system, feature_size, results=())[source]¶

Container class for the result of the identification step.

coordinate_system¶

The coordinate system of the problem.

Type: CoordinateSystem

results¶

List of identified objects.

Type: list(IdentificationResult)

feature_size¶

The feature_size used when identifying the objects.

Type: float

classmethod from_hdf5(hdf5_handle)¶: Deserializes the object stored in HDF5 format.

class nodefinder.identify.result.IdentificationResult(positions, dimension, shape=None)[source]¶

Contains the attributes of an identified object.

positions¶

Positions of the nodal points making up the object.

Type: list(tuple(float))

shape¶

Shape of the identified object. If the shape could not be identified, it is set to None.

Type: None or NodalPoint or NodalLine

dimension¶

Dimension of the identified object. Is set to None if the dimension is ambiguous.

Type: int

classmethod from_hdf5(hdf5_handle)[source]¶: Deserializes the object stored in HDF5 format.

to_hdf5(hdf5_handle)[source]¶: Serializes the object to HDF5 format, attaching it to the given HDF5 handle (might be a HDF5 File or Dataset).

class nodefinder.identify.result.NodalPoint(position)[source]¶

Shape class defining a nodal point.

position¶

The position of the point.

Type: tuple(float)

classmethod from_hdf5(hdf5_handle)¶: Deserializes the object stored in HDF5 format.

class nodefinder.identify.result.NodalLine(graph, degree_count)[source]¶

Shape class defining a nodal line.

graph¶

A graph describing the line.

Type: networkx.Graph

classmethod from_hdf5(hdf5_handle)[source]¶: Derialize the object from the given HDF5 handle.

property shape_name¶: Describes the shape of the line, as inferred from the degree count.

to_hdf5(hdf5_handle)[source]¶: Serialize the object and store in under the given HDF5 handle.

Plotting¶

Defines functions for plotting the results of the identify step.

nodefinder.identify.plot.result(res, *, axis=None)[source]¶

Plot the result of the identify step.

Parameters

res (IdentificationResultContainer) – Result of the identify step.
axis (matplotlib.axes.Axes, optional) – Axes on which the result is plotted.

nodefinder.identify.plot.nodal_point(shape, *, axis, color, feature_size=None)[source]¶

Plot a nodal point.

Parameters

shape (NodalPoint) – Nodal point to be plotted.
axis (matplotlib.axes.Axes) – Axes on which to plot.
color (str) – Color of the point.
feature_size (float) – Distance between two nodal points at which they are considered distinct. This argument is not used in this function.

nodefinder.identify.plot.nodal_line(shape, *, axis, color, feature_size=None)[source]¶

Plot a nodal line.

Parameters

shape (NodalLine) – Nodal line to be plotted.
axis (matplotlib.axes.Axes) – Axes on which to plot.
color (str) – Color of the nodal line.
feature_size (float) – Distance between two nodal points at which they are considered distinct. Used for cutting the line when it goes across periodic boundaries.

Coordinate System¶

Defines the coordinate system class.

class nodefinder.coordinate_system.CoordinateSystem(*, limits, periodic=True)[source]¶

Defines a “box” coordinate system, which is used to calculate the distances between points, and map between fractional and real coordinates.

limits¶

Limits of the coordinates, given as a the minimum and maximum value for each dimension.

Type: numpy.ndarray

periodic¶

Determies if periodic boundary conditions are used.

Type: bool

dim¶

Dimension of the coordinate system.

Type: int

size¶

Size of the coordinate system in each dimension.

Type: numpy.ndarray

average(positions)[source]¶: Get the average position from a list of positions.

connecting_vector(pos1, pos2)[source]¶: Get the shortest vector connecting two positions.

distance(pos1, pos2)[source]¶: Get the distance between two positions.

classmethod from_hdf5(hdf5_handle)¶: Deserializes the object stored in HDF5 format.

get_frac(pos)[source]¶: Get the fractional coordinates from the real position.

get_pos(frac)[source]¶: Get the real position from the fractional coordinates.

normalize_position(pos)[source]¶: Normalize the position by mapping it into the limits for periodic boundary conditions for the periodic case.

Saving and Loading¶

Defines free functions to serialize / deserialize nodefinder objects to HDF5.

These are aliases for the functions defined in fsc.hdf5_io, meaning that they can also handle other objects which are registered with the same system.

nodefinder.io.save(obj, hdf5_file)¶: Alias for to_hdf5_file().

nodefinder.io.load(hdf5_file)¶: Alias for from_hdf5_file().