Mathematical and geometrical functions

These functions are used to perform mathematical and geometrical operations.

Mathematical functions

Notes

This module contains some general mathematical functions, e.g. series expansions and Cauchy integrals.

The mathematical functions are used by the element classes in the andfn module.

andfn.math_functions.asym_expansion(chi, coef)

Function that calculates the asymptotic expansion starting from 0 for a given point chi and an array of coefficients.

\[f(\chi) = \sum_{n=0}^{\infty} c_n \chi^{-n}\]

Parameters:

• chi (complex | np.ndarray) – A point in the complex chi-plane

• coef (np.ndarray[np.complex128]) – An array of coefficients

Returns:

res – The resulting value for the asymptotic expansion

Return type:

complex | np.ndarray

andfn.math_functions.asym_expansion_d1(chi, coef)

Function that calculates the first derivative of the asymptotic expansion starting from 0 for a given point chi and an array of coefficients.

\[f(\chi) = -\sum_{n=0}^{\infty} n c_n \chi^{-n-1}\]

Parameters:

• chi (complex | np.ndarray) – A point in the complex chi-plane

• coef (np.ndarray) – An array of coefficients

Returns:

res – The resulting value for the asymptotic expansion

Return type:

complex | np.ndarray

andfn.math_functions.taylor_series(chi, coef)

Function that calculates the Taylor series starting from 0 for a given point chi and an array of coefficients.

\[f(\chi) = \sum_{n=0}^{\infty} c_n \chi^{n}\]

Parameters:

• chi (complex | np.ndarray) – A point in the complex chi-plane

• coef (np.ndarray) – An array of coefficients

Returns:

res – The resulting value for the asymptotic expansion

Return type:

complex

andfn.math_functions.taylor_series_d1(chi, coef)

Function that calculates the first derivative of the Taylor series starting from 0 for a given point chi and an array of coefficients.

\[f(\chi) = \sum_{n=1}^{\infty} n c_n \chi^{n-1}\]

Parameters:

• chi (complex) – A point in the complex chi-plane

• coef (array_like) – An array of coefficients

Returns:

res – The resulting value for the asymptotic expansion

Return type:

complex

andfn.math_functions.well_chi(chi, q)

Function that return the complex potential for a well as a function of chi.

\[\omega = \frac{q}{2\pi} \log(\chi)\]

Parameters:

• chi (np.ndarray | complex) – A point in the complex chi plane

• q (np.float64) – The discharge eof the well.

Returns:

omega – The complex discharge potential

Return type:

np.ndarray

Geometry functions

Notes

This module contains some geometrical functions for e.g. conformal mappings and mapping between 3D space and fracture planes.

The geometrical functions are used by the element classes and to create the DFN in the andfn module.

andfn.geometry_functions.bfs_connectivity_from_adjacency(adj_indptr, adj_indices, boundary)

andfn.geometry_functions.build_fracture_adjacency(fractures_struc_array, elements_struc_array)

andfn.geometry_functions.build_indptr(counts)

andfn.geometry_functions.check_connectivity(fractures)

Function that checks the connectivity of a list of fractures. The function returns any fractures that are not connected to a constant head boundary.

Parameters:

fractures (list) – A list of fractures.

Returns:

True if all fractures are connected, False otherwise.

Return type:

bool

andfn.geometry_functions.check_connectivity_hpc(fractures_struc_array, elements_struc_array)

Drop-in replacement for check_connectivity using HPC arrays.

andfn.geometry_functions.check_connectivity_org(fractures)

Function that checks the connectivity of a list of fractures. The function returns any fractures that are not connected to a constant head boundary.

Parameters:

fractures (list) – A list of fractures.

Returns:

True if all fractures are connected, False otherwise.

Return type:

bool

andfn.geometry_functions.compute_boundary_fractures_from_elements(elements, n_fractures)

Determine which fractures are connected to boundary conditions.

Parameters:

• elements (structured array (element_dtype_hpc)) – All DFN elements.

• n_fractures (int) – Total number of fractures.

Returns:

boundary – boundary[f] == 1 if fracture f has a boundary condition.

Return type:

uint8 array of shape (n_fractures,)

andfn.geometry_functions.convert_normal_to_strike_dip(normal)

Function that converts a normal vector to a strike and dip

Parameters:

normal (np.ndarray) – The normal vector of the fracture plane.

Returns:

• strike (float) – The strike of the fracture plane.

• dip (float) – The dip of the fracture plane.

andfn.geometry_functions.convert_strike_dip_to_normal(strike, dip)

Function that converts a strike and dip to a normal vector

Parameters:

• strike (float) – The strike of the fracture plane.

• dip (float) – The dip of the fracture plane.

Returns:

normal – The normal vector of the fracture plane.

Return type:

np.ndarray

andfn.geometry_functions.convert_trend_plunge_to_normal(trend, plunge)

Function that converts a trend and plunge to a normal vector

Parameters:

• trend (float) – The trend of the fracture plane.

• plunge (float) – The plunge of the fracture plane.

Returns:

normal – The normal vector of the fracture plane.

Return type:

np.ndarray

andfn.geometry_functions.copy_dfn(fractures)

This function creates a copy of a list of fractures. This is used to create a new list of fractures with the same properties as the original list, but with different intersection elements.

The copy included only the fractures and the intersections.

Parameters:

fractures (list) – A list of fractures to copy.

Returns:

fracs – A new list of fractures with the same properties as the original list, but with different intersection elements.

Return type:

list

andfn.geometry_functions.count_fracture_adjacency_from_fractures(fractures, elements)

andfn.geometry_functions.fill_fracture_adjacency_from_elements(elements, adj_indptr, adj_indices)

andfn.geometry_functions.fracture_intersection(frac0, frac1)

andfn.geometry_functions.fracture_intersection_org(frac0, frac1)

Function that calculates the intersection between two fractures.

Parameters:

• frac0 (Fracture) – The first fracture.

• frac1 (Fracture) – The second fracture.

Returns:

• endpoints0 (np.ndarray) – The endpoints of the intersection line in the first fracture. If no intersection is found, None is returned.

• endpoints1 (np.ndarray) – The endpoints of the intersection line in the second fracture. If no intersection is found, None is returned.

andfn.geometry_functions.generate_fractures(n_fractures, radius_factor=1.0, center_factor=10.0, ncoef=10, nint=20)

Function that generates a number of fractures with random radii, centers and normals.

Parameters:

• n_fractures (int) – Number of fractures to generate.

• radius_factor (float) – The maximum radius of the fractures.

• center_factor (float) – The maximum distance from the origin of the centers of the fractures.

• ncoef (int) – The number of coefficients for the bounding circle.

• nint (int) – The number of integration points for the bounding circle.

Returns:

fractures – A list of the generated fractures.

Return type:

list

andfn.geometry_functions.get_chi_from_theta(nint, start, stop)

Function that creates an array with chi values for a given number of points along the unit circle.

Parameters:

• nint (int) – Number of instances to generate

• start (float) – Start point

• stop (float) – Stop point

Returns:

chi – Array with chi values

Return type:

np.ndarray

andfn.geometry_functions.get_connected_fractures(fractures, se_factor, ncoef=5, nint=10, fracture_surface=None, tolerance=-1)

Function that finds all connected fractures in a list of fractures. Starting from the first fracture in the list, or a given fracture, the function iterates through the list of fractures and finds all connected fractures.

Parameters:

• fractures (list) – A list of fractures.

• se_factor (float) – The shortening element factor. This is used to shorten the intersection line between two fractures.

• ncoef (int) – The number of coefficients for the intersection elements.

• nint (int) – The number of integration points for the intersection elements.

• fracture_surface (Fracture) – The fracture to start the search from. If None, the first fracture in the list is used.

Returns:

connected_fractures – A list of connected fractures.

Return type:

list

andfn.geometry_functions.get_fracture_intersections(fractures, se_factor, ncoef=5, nint=10, tolerance=-1, tree=None)

Function that finds all connected fractures in a list of fractures. Starting from the first fracture in the list, or a given fracture, the function iterates through the list of fractures and finds all connected fractures.

Parameters:

• fractures (list) – A list of fractures.

• se_factor (float) – The shortening element factor. This is used to shorten the intersection line between two fractures.

• ncoef (int) – The number of coefficients for the intersection elements.

• nint (int) – The number of integration points for the intersection elements.

• tolerance (float, optional) – The minimum length of the intersection line as a fraction of the fracture radius. Intersections shorter than this value will be ignored. If -1, no tolerance is applied. Default is -1.

• tree (KDTree, optional) – A KDTree object for spatial indexing of the fracture centers. If None, a new KDtree will be created. Default is None.

Returns:

connected_fractures – A list of connected fractures.

Return type:

list

andfn.geometry_functions.get_fracture_intersections_org(fractures, se_factor, ncoef=5, nint=10, tolerance=-1)

Function that finds all connected fractures in a list of fractures. Starting from the first fracture in the list, or a given fracture, the function iterates through the list of fractures and finds all connected fractures.

Parameters:

• fractures (list) – A list of fractures.

• se_factor (float) – The shortening element factor. This is used to shorten the intersection line between two fractures.

• ncoef (int) – The number of coefficients for the intersection elements.

• nint (int) – The number of integration points for the intersection elements.

• tolerance (float, optional) – The minimum length of the intersection line as a fraction of the fracture radius. Intersections shorter than this value will be ignored. If -1, no tolerance is applied. Default is -1.

Returns:

connected_fractures – A list of connected fractures.

Return type:

list

andfn.geometry_functions.line_circle_intersection(z0, z1, radius)

Function that calculates the intersection between a line and a circle.

Parameters:

• z0 (complex) – A point on the line.

• z1 (complex) – Another point on the line.

• radius (float) – The radius of the circle.

Returns:

• z_0 (complex) – The first intersection point. If no intersection is found, None is returned.

• z_1 (complex) – The second intersection point. If no intersection is found, None is returned.

andfn.geometry_functions.line_line_intersection(z0, z1, z2, z3)

Function that calculates the intersection between two lines.

Parameters:

• z0 (complex) – A point on the first line.

• z1 (complex) – Another point on the first line.

• z2 (complex) – A point on the second line.

• z3 (complex) – Another point on the second line.

Returns:

z – The intersection point. If no intersection is found, None is returned.

Return type:

complex

andfn.geometry_functions.map_2d_to_3d(z, fractures)

Function that maps a point in the complex z-plane to a point in the 3D plane

\[x_i = x u_i + y v_i + x_{i,0}\]

Parameters:

• z (complex | np.ndarray) – A point in the complex z-plane

• fractures (Fracture) – The fracture object

Returns:

point – The corresponding point in the 3D plane

Return type:

np.ndarray

andfn.geometry_functions.map_3d_to_2d(point, fractures)

Function that maps a point in the 3D plane to a point in the complex z-plane.

\[x = \left( x_i - x_{i,0} \right) u_i\]

\[y = \left( x_i - x_{i,0} \right) v_i\]

\[z = x + iy\]

Parameters:

• point (np.ndarray) – A point in the 3D plane

• fractures (Fracture) – The fracture object

Returns:

z – The corresponding point in the complex z-plane

Return type:

complex

andfn.geometry_functions.map_chi_to_z_circle(chi, r, center=0.0)

Function that maps the unit circle in the complex chi-plane to a circle in the complex z-plane.

\[z = \chi r + \text{center}\]

Parameters:

• chi (complex | np.ndarray) – A point in the complex chi-plane

• r (float) – Radius of the circle

• center (complex or np.ndarray) – Center point of the circle

Returns:

z – The corresponding point in the complex z-plane

Return type:

complex | np.ndarray

andfn.geometry_functions.map_chi_to_z_line(chi, endpoints)

Function that maps the exterior of the unit circle in the complex chi-plane onto the exterior of a line in the complex z-plane.

\[Z = \frac{1}{2} \left( \chi + \frac{1}{\chi} \right)\]

\[z = \frac{1}{2} \left( Z \left(\text{endpoints}[1] - \text{endpoints}[0] \right) + \text{endpoints}[0] + \text{endpoints}[1]\right)\]

Parameters:

• chi (complex | np.ndarray) – A point in the complex chi-plane

• endpoints (list | np.ndarray) – Endpoints of the line in the complex z-plane

Returns:

z – The corresponding point in the complex z-plane

Return type:

complex | np.ndarray

andfn.geometry_functions.map_z_circle_to_chi(z, r, center=0.0)

Function that maps a circle in the complex z-plane onto a unit circle in the complex chi-plane.

\[\chi = \frac{z - \text{center}}{r}\]

Parameters:

• z (complex | np.ndarray) – A point in the complex z-plane

• r (float) – Radius of the circle

• center (complex | np.ndarray) – Center point of the circle in the complex z-plane

Returns:

chi – The corresponding point in the complex chi-plane

Return type:

np.ndarray

andfn.geometry_functions.map_z_line_to_chi(z, endpoints)

Function that maps the exterior of a line in the complex z-plane onto the exterior of the unit circle in the complex chi-plane.

\[Z =\]

rac{ 2z - ext{endpoints}[0] - ext{endpoints}[1] }{ ext{endpoints}[1] - ext{endpoints}[0]}

\[\chi = \frac{1}{2} \left( z + \sqrt{z - 1} \sqrt{z + 1} \right)\]

zcomplex | np.ndarray

A complex point in the complex z-plane

endpointsnp.ndarray

Endpoints of the line in the complex z-plane

chicomplex | np.ndarray

The corresponding point in the complex chi-plane

andfn.geometry_functions.remove_isolated_fractures(fractures)

Function that removes isolated fractures from a list of fractures. An isolated fracture is a fracture that does not have any intersection with other fractures.

Parameters:

fractures (list) – A list of fractures.

Returns:

fractures – A list of fractures with isolated fractures removed.

Return type:

list

andfn.geometry_functions.set_head_boundary(fractures, ncoef, nint, head, center, radius, normal, label, se_factor, tolerance)

Function that sets a constant head boundary condition on the intersection line between a fracture and a defined fracture. The constant head lines are added to the fractures in the list.

Parameters:

• fractures (list) – A list of fractures.

• ncoef (int) – The number of coefficients for the constant head line.

• nint (int) – The number of integration points for the constant head line.

• head (float) – The hydraulic head value.

• center (np.ndarray) – The center of the constant head fracture plane.

• radius (float) – The radius of the constant head fracture plane.

• normal (np.ndarray) – The normal vector of the constant head fracture plane.

• label (str) – The label of the constant head fracture plane.

• se_factor (float) – The shortening element factor. This is used to shorten the constant head line.

• tolerance (float) – The minimum length of the intersection line as a fraction of the fracture radius. Intersections shorter than this value will be ignored. If -1, no tolerance is applied. Default is -1.

Return type:

None

andfn.geometry_functions.set_impermeable_boundary(fractures, ncoef, nint, center, radius, normal, label, se_factor)

Function that sets an impermeable boundary condition on the intersection line between a fracture and a defined fracture. The impermeable lines are added to the fractures in the list.

Parameters:

• fractures (list) – A list of fractures.

• ncoef (int) – The number of coefficients for the constant head line.

• nint (int) – The number of integration points for the constant head line.

• center (np.ndarray) – The center of the constant head fracture plane.

• radius (float) – The radius of the constant head fracture plane.

• normal (np.ndarray) – The normal vector of the constant head fracture plane.

• label (str) – The label of the constant head fracture plane.

• se_factor (float) – The shortening element factor. This is used to shorten the constant head line.

Return type:

None

andfn.geometry_functions.shorten_line(endpoints, se_factor)

Function that shortens a line segment by a given se_factor and keeps the same center point.

Parameters:

• endpoints (np.ndarray) – The endpoints of the line segment.

• se_factor (float)

Return type:

np.ndarray

andfn.geometry_functions.split_crossing_elements(fractures)

Function that splits crossing intersection elements in a list of fractures. If two intersection elements cross each other, they are split into four new intersection elements.

Parameters:

fractures (list) – A list of fractures.

Returns:

fractures – A list of fractures with crossing intersection elements split.

Return type:

list