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 “pointcloud” 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=1e06, 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 NelderMead 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 rechecking the position.
simplex_check_cutoff (int) – Number of vertices which are allowed to be within the cutoff distance when rechecking the simplex.
 Returns
The result of the search algorithm.
 Return type

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

child
¶ Result of the second minimization run.
 Type

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

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

simplex_history
¶ History of simplex values.
 Type
ndarray, optional

fun_simplex_history
¶ History of function values of the simplex.
 Type
ndarray, optional


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

nodes
¶ Minimization results which fulfill the gap threshold criterion.
 Type

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.


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.

classmethod
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()
.
Identify¶
Run function¶
Submodule for identifying nodal features such as points and lines from a
pointcloud 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

results
¶ List of identified objects.
 Type

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.

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


class
nodefinder.identify.result.
NodalPoint
(position)[source]¶ Shape class defining a nodal point.

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

classmethod
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

size
¶ Size of the coordinate system in each dimension.
 Type

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

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()
.