porepy.fracs.fracture_network_3d module

A module for representation and manipulations of fractures and fracture sets.

The model relies heavily on functions in the computational geometry library.

class FractureNetwork3d(fractures=None, domain=None, tol=1e-8, run_checks=False)

Bases: object

Collection of Fractures with geometrical information. Facilitates computation of intersections of the fracture. Also incorporates the bounding box of the domain. To ensure that all fractures lie within the box, call impose_external_boundary() _after_ all fractures have been specified.

Parameters

• fractures (Optional[list[PlaneFracture]]) –

• domain (Optional[Union[dict[str, float], list[np.ndarray]]]) –

• tol (float) –

• run_checks (bool) –

_fractures

All fractures forming the network.

Type

list of Fracture

intersections

All known intersections in the network.

Type

list of Intersection

has_checked_intersections

If True, the intersection finder method has been run. Useful in meshing algorithms to avoid recomputing known information.

Type

boolean

tol

Geometric tolerance used in computations.

Type

double

domain

External bounding box. See impose_external_boundary() for details.

Type

dictionary

tags

Tags used on Fractures and subdomain boundaries.

Type

dictionary

mesh_size_min

Mesh size parameter, minimum mesh size to be sent to gmsh. Set by insert_auxiliary_points().

Type

double

mesh_size_frac

Mesh size parameter. Ideal mesh size, fed to gmsh. Set by insert_auxiliary_points().

Type

double

mesh_size_bound

Mesh size parameter. Boundary mesh size, fed to gmsh. Set by insert_auxiliary_points().

Type

double

auxiliary_points_added

Mesh size parameter. If True, extra points have been added to Fracture geometry to facilitate mesh size tuning.

Type

boolean

decomposition

Splitting of network, accounting for fracture intersections etc. Necessary pre-processing before meshing. Added by split_intersections().

Type

dictionary

add(f)

Add a fracture to the network.

The fracture will be assigned a new index, higher than the maximum value currently found in the network.

Parameters

f (Fracture) – Fracture to be added.

bounding_box()

Obtain bounding box for fracture network.

The box is defined by the external boundary, if imposed, or if not by the maximal extent of the fractures in each direction.

Returns

dictionary with fields ‘xmin’, ‘xmax’, ‘ymin’, ‘ymax’, ‘zmin’,

’zmax’

close_points(dist)

In the set of points used to describe the fractures (after decomposition), find pairs that are closer than a certain distance. Intended use: Debugging.

Parameters

dist (double) – Threshold distance, all points closer than this will be reported.

Returns

Each tuple contain indices of a set of close

points, and the distance between the points. The list is not symmetric; if (a, b) is a member, (b, a) will not be.

Return type

List of tuples

copy()

Create deep copy of the network.

The method will create a deep copy of all fractures, as well as the domain, of the network. Note that if the fractures have had extra points imposed as part of a meshing procedure, these will be included in the copied fractures.

Returns

pp.FractureNetwork3d.

find_intersections(use_orig_points=False)

Find intersections between fractures in terms of coordinates.

The intersections are stored in the attribute self.Intersections.

Handling of the intersections (splitting into non-intersecting polygons, paving the way for gridding) is taken care of by the function split_intersections().

Note that find_intersections() should be invoked after external boundaries are imposed. If the reverse order is applied, intersections outside the domain may be identified, with unknown consequences for the reliability of the methods. If intersections outside the bounding box are of interest, these can be found by setting the parameter use_orig_points to True.

Parameters

use_orig_points (boolean, optional) – Whether to use the original fracture description in the search for intersections. Defaults to False. If True, all fractures will have their attribute p reset to their original value.

fracture_to_plane(frac_num)

Project fracture vertexes and intersection points to the natural plane of the fracture.

Parameters

frac_num (int) – Index of fracture.

Returns

2d coordinates of the fracture vertexes. np.ndarray (2xn_isect): 2d coordinates of fracture intersection

points.

np.ndarray: Index of intersecting fractures. np.ndarray, 3x3: Rotation matrix into the natural plane. np.ndarray, 3x1. 3d coordinates of the fracture center.

The 3d coordinates of the fracture can be recovered by

p_3d = cp + rot.T.dot(np.vstack((p_2d,

np.zeros(p_2d.shape[1]))))

Return type

np.ndarray (2xn_pt)

fractures_of_points(pts)

For a given point, find all fractures that refer to it, either as vertex or as internal.

Returns

indices of fractures, one list item per point.

Return type

list of int

impose_external_boundary(domain=None, keep_box=True, area_threshold=1e-4, clear_gmsh=True, finalize_gmsh=True)

Set an external boundary for the fracture set.

There are two permissible data formats for the domain boundary:

1. A 3D box, described by its minimum and maximum coordinates.

2. A list of polygons (each specified as a np.array, 3xn), that together

   form a closed polyhedron.

If no bounding box is provided, a box will be fitted outside the fracture network.

The fractures will be truncated to lay within the bounding box; that is, Fracture.pts will be modified. The original coordinates of the fracture boundary can still be recovered from the attribute Fracture.orig_points.

Fractures that are completely outside the bounding box will be deleted from the fracture set.

Parameters

domain (dictionary or list of np.ndarray): See above for description. keep_box (bool, optional): If True (default), the bounding surfaces will be

added to the end of the fracture list, and tagged as boundary.

area_threshold (float): Lower threshold for how much of a fracture’s area

should be within the bounding box for the fracture to be preserved. Defaults to 1e-4

finalize_gmsh and clear_gmsh

are needed in the context of potentially non-convex fractures. The values used here should be the same as in a call to self.mesh(); default values should be sufficient for all regular usage.

Returns

np.array: Mapping from old to new fractures, referring to the fractures in

self._fractures before and after imposing the external boundary. The mapping does not account for the boundary fractures added to the end of the fracture array (if keep_box) is True.

Raises

ValueError

If the FractureNetwork contains no fractures and no domain was passed to this method.

Parameters

• domain (Optional[Union[dict[str, float], list[numpy.ndarray]]]) –

• keep_box (bool) –

• area_threshold (float) –

• clear_gmsh (bool) –

• finalize_gmsh (bool) –

Return type

ndarray

intersections_of_fracture(frac)

Get all known intersections for a fracture.

If called before find_intersections(), the returned list will be empty.

Parameters

frac (Union[int, PlaneFracture]) – A fracture in the network

Returns

Array of intersections

Return type

np.array (Intersection)

mesh(mesh_args, dfn=False, file_name=None, constraints=None, write_geo=True, tags_to_transfer=None, finalize_gmsh=True, clear_gmsh=False, **kwargs)

Mesh the fracture network, and generate a mixed-dimensional grid.

The mesh itself is generated by Gmsh.

Parameters

• mesh_args (dict) – Should contain fields ‘mesh_size_frac’, ‘mesh_size_min’, which represent the ideal mesh size at the fracture, and the minimum mesh size passed to gmsh. Can also contain ‘mesh_size_bound’, which gives the far-field (boundary) mesh size.

• dfn (boolean, optional) – If True, a DFN mesh (of the network, but not the surrounding matrix) is created.

• file_name (str, optional) –

  Name of file used to communicate with gmsh.

  defaults to gmsh_frac_file. The gmsh configuration file will be file_name.geo, while the mesh is dumped to file_name.msh.

• constraints (np.array) – Index list of elements in the fracture list that should be treated as constraints in meshing, but not added as separate fracture grids (no splitting of nodes etc.).

• write_geo (bool, optional) – If True (default), the gmsh configuration will be written to a .geo_unrolled file.

• tags_to_transfer (list of strings, optional) – Tags, in self.tags to be transferred to the fracture grids. Provisional functionality.

• finalize_gmsh (boolean) – If True (default), the port to Gmsh is closed when meshing is completed. On repeated invocations of Gmsh in the same Python session, a memory leak in Gmsh may cause reduced performance (written spring 2021). In these cases, it may be better to finalize gmsh externally to this class. See also clear_gmsh.

• clear_gmsh (boolean, optional) – If True, the geometry representation in gmsh is deleted when meshing is completed. This is of use only if finalize_gmsh is set to False, in which case it may be desirable to delete the old geometry before adding a new one. Defaults to False.

Returns

Mixed-dimensional mesh.

Return type

MixedDimensionalGrid

num_frac()

Get number of fractures in the network, not counting planes on the domain boundary.

Returns

Number of network fractures.

Return type

int

prepare_for_gmsh(mesh_args, dfn=False, constraints=None)

Process network intersections and write a gmsh .geo configuration file, ready to be processed by gmsh.

NOTE: Consider using the mesh() function instead to get a ready MixedDimensionalGrid.

Parameters

• mesh_args (dict) – Should contain fields ‘mesh_size_frac’, ‘mesh_size_min’, which represent the ideal mesh size at the fracture, and the minimum mesh size passed to gmsh. Can also contain ‘mesh_size_bound’, which gives the far-field (boundary) mesh size.

• dfn (boolean, optional) – If True, a DFN mesh (of the network, but not the surrounding matrix) is created.

• constraints (np.array) – Index list of elements in the fracture list that should be treated as constraints in meshing, but not added as separate fracture grids (no splitting of nodes etc.).

Returns

Name of .geo file.

Return type

str

split_intersections()

Based on the fracture network, and their known intersections, decompose the fractures into non-intersecting sub-polygons. These can subsequently be exported to gmsh.

The method will add an attribute decomposition to self.

to_csv(file_name, domain=None)

Save the 3d network on a csv file with comma , as separator. Note: the file is overwritten if present. The format is - if domain is given the first line describes the domain as a rectangle

X_MIN, Y_MIN, Z_MIN, X_MAX, Y_MAX, Z_MAX

• the other lines describe the N fractures as a list of points P0_X, P0_Y, P0_Z, …,PN_X, PN_Y, PN_Z

Parameters

• file_name – name of the file

• domain – (optional) the bounding box of the problem

to_fab(file_name)

Save the 3d network on a fab file, as specified by FracMan.

The filter is based on the .fab-files needed at the time of writing, and may not cover all options available.

Parameters

file_name (str) – File name.

to_file(file_name, data=None, **kwargs)

Export the fracture network to file.

The file format is given as an kwarg, by default vtu will be used. The writing is outsourced to meshio, thus the file format should be supported by that package.

The fractures are treated as polygonal cells, with no special treatment of intersections.

Fracture numbers are always exported (1-offset). In addition, it is possible to export additional data, as specified by the keyword-argument data.

Parameters

• file_name (str) – Name of the target file.

• data (dictionary, optional) – Data associated with the fractures. The values in the dictionary should be numpy arrays. 1d and 3d data is supported. Fracture numbers are always exported.

Return type

None

Optional arguments in kwargs:

binary (boolean): Use binary export format. Default to

True.

fracture_offset (int): Use to define the offset for a

fracture id. Default to 1.

folder_name (string): Path to save the file. Default to “./”. extension (string): File extension. Default to “.vtu”.

See also the functions self.to_fab() and self.to_csv().