FoldOptLib.optimisers package

Submodules

FoldOptLib.optimisers.axial_surface_optimiser module

class FoldOptLib.optimisers.axial_surface_optimiser.AxialSurfaceOptimiser(data: DataFrame, bounding_box: list | ndarray, geological_knowledge: Dict[str, Any] | None = None, **kwargs: Dict[str, Any])

Bases: FoldOptimiser

Optimiser for Axial Surfaces.

This class inherits from FoldOptimiser, FoldModel. It is used to optimise the axial surfaces based on the provided data, bounding box, geological knowledge.

angle_optimisation(strike_dip: Tuple[float, float])

Minimises the angle between the observed and predicted folded foliation.

Parameters:

strike_dip (tuple) – A tuple containing strike and dip values of the estimated axial surface.

Returns:

angle_difference – The difference between the predicted and actual angle.

Return type:

float

Notes

This function optimises the axial surface by minimising the angle between the predicted and observed folded foliation. This function is used when there are no geological knowledge constraints provided.

generate_initial_guess()

Generate the initial guess for the optimisation for differential evolution algorithm. The initial guess is generated using the Von Mises Fisher distribution.

loglikelihood(x, predicted_foliation: ndarray, geological_knowledge: GeologicalKnowledgeFunctions) → float

Calculate the maximum likelihood estimate of the axial surface and the geological knowledge.

Parameters:

• x (np.ndarray) – The axial surface normal vector to be optimised.

• predicted_foliation (np.ndarray) – The predicted foliation data.

• geological_knowledge (GeologicalKnowledgeFunctions) – The geological knowledge functions.

Returns:

The calculated loglikelihood of the axial surface. Returns None if input is not valid.

Return type:

float

mle_optimisation(strike_dip: Tuple[float, float])

Performs Maximum Likelihood Estimation (MLE) optimisation.

Parameters:

strike_dip (tuple) – A tuple containing strike and dip values of the estimated axial surface.

Returns:

logpdf – The log-likelihood of the MLE.

Return type:

float

Notes

This function performs MLE optimisation and used when geological knowledge constraints are provided. The function returns the log-likelihood of the MLE that is optimised

optimise(geological_knowledge: Dict[str, Any] | None = None) → Dict[str, Any]

Runs the optimisation.

Parameters:

geological_knowledge (dict, optional) – A dictionary containing geological knowledge. Default is None.

Returns:

opt – The result of the optimisation.

Return type:

Dict

Notes

This function runs the optimisation by setting up the optimisation problem, checking if geological knowledge exists, and running the solver.

setup_optimisation(geological_knowledge: Dict[str, Any] | None = None)

Sets up the optimisation algorithm.

Parameters:

geological_knowledge (dict, optional) – A dictionary containing geological knowledge. Default is None.

Returns:

• objective_function (callable) – The objective function to be minimised.

• _geological_knowledge (dict or None) – The geological knowledge objective functions.

• solver (BaseOptimiser) – The solver from BaseOptimiser to be used for optimisation.

• guess (Union[np.ndarray, str]) – The initial guess for the optimisation.

FoldOptLib.optimisers.axial_surface_optimiser.calculate_intersection_lineation(axial_surface, folded_foliation)

Calculate the intersection lineation of the axial surface and the folded foliation.

Parameters: axial_surface (np.ndarray): The normal vector of the axial surface. folded_foliation (np.ndarray): The normal vector of the folded foliation.

Returns: np.ndarray: The normalised intersection lineation vector.

FoldOptLib.optimisers.base_optimiser module

FoldOptLib.optimisers.fold_optimiser module

class FoldOptLib.optimisers.fold_optimiser.FoldOptimiser(method='differential_evolution', **kwargs: Dict[str, Any])

Bases: ABC

Base class for fold geometry optimisation.

abstract generate_initial_guess()

Generate an initial guess for the optimisation It generates a guess depending on the type of optimisation, if it’s fourier series it will generate a guess of the wavelength, if it’s axial surface it will generate a guess using the methods of the Differential Evolution algorithm (Stern and Price, 1997) or uses the Von Mises Fisher distribution (Fisher, 1953).

abstract optimise(*args, **kwargs)

Run the optimisation

optimise_with_differential_evolution(objective_function: Callable, bounds: Tuple, init: str = 'halton', maxiter: int = 5000, seed: int = 80, polish: bool = False, strategy: str = 'best2exp', mutation: Tuple[float, float] = (0.3, 0.99), **kwargs) → Dict

Solves the optimization problem using the differential evolution method. Check Scipy documentation for more info

Parameters:

• bounds (Tuple) – Bounds for variables. (min, max) pairs for each element in x, defining the bounds on that parameter.

• init (str) – Specify how population initialisation is performed. Default is ‘halton’.

• maxiter (int) – The maximum number of generations over which the entire population is evolved. Default is 5000.

• seed (int) – The seed for the pseudo-random number generator. Default is 80.

• polish (bool) – If True (default), then differential evolution is followed by a polishing phase.

• strategy (str) – The differential evolution strategy to use. Default is ‘best2exp’.

• mutation (Tuple[float, float]) – The mutation constant. Default is (0.3, 0.99) and it was tested and have proven to explore the parameter space efficiently.

Returns:

opt – The solution of the optimization. :param objective_function:

Return type:

Dict

optimise_with_trust_region(objective_function: Callable, x0: ndarray, constraints=None, **kwargs) → Dict

Solves the optimization problem using the trust region method.

Parameters:

x0 (np.ndarray) – Initial guess of the parameters to be optimised.

Returns:

opt – The solution of the optimisation.

Return type:

Dict

prepare_and_setup_knowledge_constraints(geological_knowledge=None) → list[NonlinearConstraint] | GeologicalKnowledgeFunctions | None

Prepare the knowledge constraints data

abstract setup_optimisation(geological_knowledge=None) → tuple

Setup optimisation.

Returns:

Returns a tuple containing the geological knowledge objective functions, a solver, and the initial guess.

Return type:

tuple

FoldOptLib.optimisers.fourier_optimiser module

class FoldOptLib.optimisers.fourier_optimiser.FourierSeriesOptimiser(fold_frame_coordinate: list | ndarray, rotation_angle: list | ndarray, x: list | ndarray, method='differential_evolution', **kwargs: Dict[str, Any])

Bases: FoldOptimiser

A class used to represent a Fourier Series Optimiser.

…

fold_frame_coordinate

The fold frame coordinate for the optimiser.

Type:

float

rotation_angle

The rotation angle for the optimiser.

Type:

float

knowledge_constraints

The knowledge constraints for the optimiser.

Type:

dict, optional

x

The interpolated fold frame coordinate z or y: np.linspace(z.min(), z.max(), 100). It’s used to calculate the optimised Fourier series everywhere in the model space.

Type:

float

kwargs

Additional keyword arguments.

Type:

dict

TODO: Add methods here.

generate_initial_guess() → ndarray | Any

Generate an initial guess for the optimisation. It generates a guess of the wavelength for the Fourier series. The format of the guess depends on the method of optimisation - differential evolution or trust region. If it’s differential evolution, it will generate the bounds for the optimisation. If it’s trust region, it will generate the initial guess of the wavelength.

Returns:

Returns the initial guess or bounds for the optimisation.

Return type:

np.ndarray or Any

optimise(geological_knowledge=None, **kwargs) → Dict[str, Any]

Optimise the Fourier series.

Returns:

Returns the result of the optimisation.

Return type:

Dict[str, Any]

setup_optimisation(geological_knowledge=None) → Tuple[Callable, GeologicalKnowledgeFunctions | None, Callable, Any]

Setup Fourier series optimisation.

Returns:

Returns a tuple containing the objective function, geological knowledge, solver, and initial guess.

Return type:

tuple

Module contents