FoldOptLib.objective_functions package

Submodules

FoldOptLib.objective_functions.axial_plane module

FoldOptLib.objective_functions.axial_plane.is_axial_plane_compatible(v1: ndarray, v2: ndarray) → float

Calculate the angle difference between the predicted bedding and the observed one.

This is an objective function that verifies if the predicted and observed bedding or folded foliation are geometrically compatible. If the sum of the calculated angles is close to 0 degrees, the axial plane of the predicted folded foliation is representative of the axial surface of observed folded foliation.

Parameters:

• v1 (np.ndarray) – The first vector representing the predicted bedding.

• v2 (np.ndarray) – The second vector representing the observed bedding.

Returns:

The angle difference between the predicted and observed bedding.

Return type:

np.ndarray

Raises:

ValueError – If v1 and v2 are not numpy arrays of the same shape.

FoldOptLib.objective_functions.gaussian module

FoldOptLib.objective_functions.gaussian.gaussian_log_likelihood(b: int | float, mu: int | float, sigma: int | float) → float

Calculate the log-likelihood of a Gaussian distribution.

This function calculates the log-likelihood of a Gaussian distribution for a given observed value, mean, and standard deviation. The formula used is the standard formula for the log-likelihood of a Gaussian distribution.

Parameters:

• b (Union[int, float]) – The observed value.

• mu (Union[int, float]) – The mean of the Gaussian distribution.

• sigma (Union[int, float]) – The standard deviation of the Gaussian distribution.

Returns:

The calculated log-likelihood.

Return type:

float

Raises:

ValueError – If sigma is less than or equal to 0.

FoldOptLib.objective_functions.gaussian.loglikelihood(y, y_pred)

FoldOptLib.objective_functions.gaussian.loglikelihood_axial_surface(x: float) → int | float

Objective function for the axial surface. This function calculates the loglikelihood of an axial surface using the VonMisesFisher distribution.

Parameters:

x (float) – represents the angle between the observed folded foliation and the predicted one.

Returns:

The logpdf value from the VonMises distribution.

Return type:

Union[int, float]

FoldOptLib.objective_functions.gaussian.loglikelihood_fourier_series(rotation_angle, fold_frame_coordinate)

FoldOptLib.objective_functions.geological_knowledge module

class FoldOptLib.objective_functions.geological_knowledge.GeologicalKnowledgeFunctions(constraints: Dict[str, float])

Bases: SPlotProcessor

Base class for geological knowledge objective functions

asymmetry_objective_function(theta: ndarray) → float

Calculate the objective function for the ‘asymmetry’ constraint.

This function calculates the likelihood of the fold asymmetry degree given the constraints.

Parameters:

theta (np.ndarray) – The Fourier series parameters. These are the parameters of the Fourier series used to calculate the fold limb rotation angle curve.

Returns:

The calculated objective function value. This is the likelihood of the fold asymmetry degree.

Return type:

float

Raises:

• TypeError – If theta is not a numpy array.

• ValueError – If theta does not have at least 4 parameters.

axial_surface_objective_function(v: ndarray) → float

Objective function for the axial surface. This function calculates the loglikelihood of an axial surface using the VonMisesFisher distribution.

Parameters:

v (np.ndarray) – the unit vector that represents the axial surface. This is evaluated every iteration in the optimisation process

Returns:

• float – The logpdf value from the VonMisesFisher distribution.

  Raises

• ——

• KeyError

• If the required keys are not found in the constraints dictionary.

axial_trace_objective_function(theta: ndarray) → int | float

Calculate the objective function for the ‘axial_trace’ constraint.

This function calculates the negative likelihood of the axial trace(s) given the provided knowledge constraints.

Parameters:

theta (np.ndarray) – The Fourier series parameters. These are the parameters of the Fourier series used to calculate the axial traces.

Returns:

The calculated objective function value. This is the likelihood of the axial trace(s). If there are no axial traces, the function returns a predefined constant value (999) that

penalise the minimisation algorithm.

Return type:

Union[int, float]

fold_axis_wavelength_objective_function(theta: ndarray) → float

Calculate the objective function for the fold axis wavelength constraint.

This function calculates the negative likelihood of the fold axis wavelength given the constraints.

Parameters:

theta (np.ndarray) – The Fourier series parameters. These are the parameters of the Fourier series used to calculate the fold axis rotation angle curve.

Returns:

The calculated objective function value. This is the likelihood of the fold axis wavelength.

Return type:

float

Raises:

• TypeError – If theta is not a numpy array.

• ValueError – If theta does not have at least 4 parameters.

hinge_angle_objective_function(theta: ndarray) → float

Calculate the objective function for the ‘hinge_angle’ constraint.

This function calculates the likelihood of the fold hinge angle given the constraints.

Parameters:

theta (np.ndarray) – The Fourier series parameters. These are the parameters of the Fourier series used to calculate the fold axis rotation angle curve.

Returns:

The calculated objective function value. This is the likelihood of the fold hinge angle.

Return type:

float

Raises:

• TypeError – If theta is not a numpy array.

• ValueError – If theta does not have at least 4 parameters.

setup_objective_functions()

Setup the mapping between constraint names and their corresponding objective function methods.

This function creates a dictionary where the keys are the names of the constraints and the values are the corresponding objective function methods. This mapping is used to dynamically call the correct objective function based on the constraint name.

setup_objective_functions_for_restricted_mode() → List[NonlinearConstraint]

This function prepares the constraints by calculating the lower and upper bounds for each constraint and setting up the NonlinearConstraint objects from scipy.optimize. It also sets up the constraint functions.

This function is used only when the optimisation is in a restricted mode. The restricted mode means that the optimisation algorithm cannot leave the parameter space defined by the geological knowledge constraints. The drawback of fitting a fold rotation angle model in this mode is that if the constraints provided are not representative of the studied fold geometry, the fitted model will be as well not representative.

Returns:

A list of NonlinearConstraint objects for each constraint.

Return type:

List[NonlinearConstraint]

Raises:

TypeError – If the constraint info is not a dictionary.

tightness_objective_function(theta: ndarray) → float

Calculate the objective function for the ‘tightness’ constraint.

This function calculates the likelihood of the fold tightness given the constraints.

Parameters:

theta (np.ndarray) – The Fourier series parameters. These are the parameters of the Fourier series used to calculate the fold limb rotation angle curve.

Returns:

The calculated objective function value. This is the likelihood of the fold tightness.

Return type:

float

Raises:

• TypeError – If theta is not a numpy array.

• ValueError – If theta does not have at least 4 parameters.

wavelength_objective_function(theta: ndarray) → float

Calculate the objective function for the fold wavelength constraint.

This function calculates the negative likelihood of the fold wavelength given the knowledge constraints.

Parameters:

theta (np.ndarray) – The Fourier series parameters. These are the parameters of the Fourier series used to calculate the fold limb rotation angle curve.

Returns:

The calculated objective function value. This is the likelihood of the fold wavelength.

Return type:

float

Raises:

• TypeError – If theta is not a numpy array.

• ValueError – If theta does not have at least 4 parameters.

FoldOptLib.objective_functions.geological_knowledge.check_fourier_parameters(theta)

FoldOptLib.objective_functions.lambda_objective_function module

class FoldOptLib.objective_functions.lambda_objective_function.LambdaObjectiveFunction(lambda_function, name)

Bases: object

This class is used to create a lambda objective function.

make_objective_function(*args, **kwargs)

This method is wrapper that takes an objective function and prepares it for use in the optimiser.

FoldOptLib.objective_functions.least_squares module

class FoldOptLib.objective_functions.least_squares.LeastSquaresFunctions(rotation_angle: ndarray, fold_frame: ndarray, knowledge_constraints: Callable, **kwargs: Dict[str, Any])

Bases: object

A class used to represent the Least Squares Functions.

…

rotation_angle

Either the calculated fold limb or axis rotation angles.

Type:

np.ndarray

fold_frame

The fold frame z or y.

Type:

np.ndarray

knowledge_constraints

A callable function that calculate the likelihood of input knowledge constraints.

Type:

Callable

kwargs

Additional keyword arguments.

Type:

Dict[str, Any]

square_residuals(theta: float) → np.ndarray:

Calculates the square residuals between observations y and predicted rotation angle _y.

huber_loss(residuals: np.ndarray, delta: float = 0.5) → np.ndarray:

Calculates the Huber loss.

soft_l1_loss(residuals: np.ndarray, delta: float = 0.5) → np.ndarray:

Calculates the Soft L1 loss.

cost(theta: float) → float:

Calculates the cost function.

cost(theta: ndarray) → float

Calculates the cost function.

Parameters:

theta (float) – The theta value.

Returns:

cost – The calculated cost.

Return type:

float

huber_loss(residuals: ndarray, delta: float = 0.5) → ndarray

Calculates the Huber loss function.

Parameters:

• residuals (np.ndarray) – The residuals.

• delta (float) – The delta value. Default is 0.5.

Returns:

s – The calculated Huber loss.

Return type:

np.ndarray

soft_l1_loss(residuals: ndarray, delta: float = 0.5) → ndarray

Calculates the Soft L1 loss function.

Parameters:

• residuals (np.ndarray) – The residuals.

• delta (float) – The delta value. Default is 0.5.

Returns:

l1 – The calculated Soft L1 loss.

Return type:

np.ndarray

square_residuals(theta: ndarray) → ndarray

Calculates the square residuals between observations y and predicted rotation angle _y.

Parameters:

theta (float) – The theta value.

Returns:

residuals – The calculated residuals.

Return type:

np.ndarray

FoldOptLib.objective_functions.von_mises_fisher module

class FoldOptLib.objective_functions.von_mises_fisher.VonMisesFisher(mu: List[float], kappa: float)

Bases: object

This class defines objective functions based on the Von Mises-Fisher (vMF) distribution. It can be used in Maximum Likelihood Estimation (MLE) optimization problems, and for drawing samples from a vMF distribution.

draw_samples(size: int = 1, random_state: int = 1) → ndarray

Draw random samples from the Von Mises-Fisher distribution.

Parameters:

• size (int, optional) – The number of random samples to draw. Default is 1.

• random_state (int, optional) – The seed for the random number generator. Default is 1.

Returns:

The array of drawn random samples. Each sample is a 3D vector

Return type:

np.ndarray

Raises:

TypeError – If size or random_state is not an integer.

logpdf(x: ndarray) → ndarray

Evaluate the logarithm of the Probability Density Function (PDF) of the Von Mises-Fisher distribution at a given point.

Parameters:

x (np.ndarray) – Points at which the logarithm of the PDF should be evaluated.

Returns:

The evaluated logarithm of the PDF at each point in x.

Return type:

np.ndarray

pdf(x: ndarray) → ndarray

Evaluate the Probability Density Function (PDF) of the Von Mises-Fisher distribution at a given point.

Parameters:

x (np.ndarray) – Points at which the PDF should be evaluated.

Returns:

The evaluated PDF at each point in x.

Return type:

np.ndarray

Module contents