porepy.fracs.fracture_network_2d module

Module contains class for representing a fracture network in a 2d domain.

class FractureNetwork2d(pts=None, edges=None, domain=None, tol=1e-8)

Bases: object

Class representation of a set of fractures in a 2D domain.

The fractures are represented by their endpoints. Poly-line fractures are currently not supported. There is no requirement or guarantee that the fractures are contained within the specified domain. The fractures can be cut to a given domain by the function constrain_to_domain().

The domain can be a general non-convex polygon.

IMPLEMENTATION NOTE: The class is mainly intended for representation and meshing of a fracture network, however, it also contains some utility functions. The balance between these components may change in the future, specifically, utility functions may be removed.

Parameters

• (siz (pts) – 2 x num_pts): Start and endpoints of the fractures. Points can be shared by fractures.

• (size (edges) – (2 + num_tags) x num_fracs): Fractures, defined as connections between the points.

• domain (Optional[dict[str, float] | np.ndarray]) – The domain in which the fracture set is defined. If dictionary, it should contain keys ‘xmin’, ‘xmax’, ‘ymin’, ‘ymax’, each of which maps to a double giving the range of the domain. If np.array, it should be of size 2 x n, and given the vertexes of the domain. The fractures need not lay inside the domain. TODO: The np.ndarray gives all kind of trouble with typing in other places. Should be dropped.

• tol (float) – Tolerance used in geometric computations.

• pts (Optional[np.ndarray]) –

• edges (Optional[np.ndarray]) –

add_network(fs)

Add this fracture set to another one, and return a new set.

The new set may contain non-unique points and edges.

It is assumed that the domains, if specified, are on a dictionary form.

WARNING: Tags, in FractureSet.edges[2:] are preserved. If the two sets have different set of tags, the necessary rows and columns are filled with what is essentially random values.

Parameters

fs (FractureSet) – Another set to be added

Returns

New fracture set, containing all points and edges in both self and

fs, and the union of the domains.

as_graph(split_intersections=True)

Represent the fracture set as a graph, using the networkx data structure.

By default, the fractures will first be split into non-intersecting branches.

Parameters

split_intersections (boolean, optional) – If True (default), the network is split into non-intersecting branches before invoking the graph representation.

Returns

Graph representation of the network, using the networkx

data structure.

FractureSet: This fracture set, split into non-intersecting branches.

Only returned if split_intersections is True

Return type

networkx.graph

compute_center(p=None, edges=None)

Compute center points of a set of fractures.

Parameters

• p (np.array, 2 x n , optional) –

  Points used to describe the fractures.

  defaults to the fractures in this set.

• edges (np.array, 2 x num_frac, optional) – Indices, referring to pts, of the start and end points of the fractures for which the centres should be computed. Defaults to the fractures of this set.

Returns

Coordinates of the centers of this fracture.

Return type

np.array, 2 x num_frac

constrain_to_domain(domain=None)

Constrain the fracture network to lay within a specified domain.

Fractures that cross the boundary of the domain will be cut to lay within the boundary. Fractures that lay completely outside the domain will be dropped from the constrained description.

TODO: Also return an index map from new to old fractures.

Parameters

domain (dictionary, None) – Domain specification, in the form of a dictionary with fields ‘xmin’, ‘xmax’, ‘ymin’, ‘ymax’. If not provided, the domain of this object will be used.

Returns

Initialized by the constrained fractures, and the

specified domain.

Return type

FractureNetwork2d

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.FractureNetwork2d.

Return type

FractureNetwork2d

See also

self.snapped_copy(), self.copy_with_split_intersections()

copy_with_split_intersections(tol=None)

Create a new FractureSet, with all fracture intersections removed

Parameters

tol (optional) – Tolerance used in geometry computations when splitting fractures. Defaults to the tolerance of this network.

Returns

New set, where all intersection points are added so that

the set only contains non-intersecting branches.

Return type

FractureSet

See also

self.copy(), self.snapped_copy()

domain_measure(domain=None)

Get the measure (length, area) of a given box domain, specified by its extensions stored in a dictionary.

The dimension of the domain is inferred from the dictionary fields.

Parameters

domain (dictionary, optional) – Should contain keys ‘xmin’ and ‘xmax’ specifying the extension in the x-direction. If the domain is 2d, it should also have keys ‘ymin’ and ‘ymax’. If no domain is specified the domain of this object will be used.

Returns

Measure of the domain.

Return type

double

end_points(fi=None)

Get start points of all fractures, or a subset.

Parameters

fi (np.array or int, optional) – Index of the fractures for which the end point should be returned. Either a numpy array, or a single int. In case of multiple indices, the points are returned in the order specified in fi. If not specified, all end points will be returned.

Returns

End coordinates of all fractures.

Return type

np.array, 2 x num_frac

get_points(fi=None)

Return start and end points for a specified fracture.

Parameters

fi (np.array or int, optional) – Index of the fractures for which the end point should be returned. Either a numpy array, or a single int. In case of multiple indices, the points are returned in the order specified in fi. If not specified, all end points will be returned.

Returns

End coordinates of all fractures. np.array, 2 x num_frac: End coordinates of all fractures.

Return type

np.array, 2 x num_frac

impose_external_boundary(domain=None, add_domain_edges=True)

Constrain the fracture network to lie within a domain.

Fractures outside the imposed domain will be deleted.

The domain will be added to self.pts and self.edges, if add_domain_edges is True. The domain boundary edges can be identified from self.tags[‘boundary’].

Parameters

• domain (dict or np.array, optional) – Domain. See __init__ for description. if not provided, self.domain will be used.

• add_domain_edges (bool, optional) – Include or not the boundary edges and pts in the list of edges. Default value True.

Returns

Index of edges that were outside the bounding box

and therefore deleted.

Return type

edges_deleted (np.array)

length(fi=None)

Compute the total length of the fractures, based on the fracture id. The output array has length as unique(frac) and ordered from the lower index to the higher.

Parameters

fi (np.array, or int) – Index of fracture(s) where length should be computed. Refers to self.edges

Returns

Length of each fracture

Return type

np.array

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

Create MixedDimensionalGrid (mixed-dimensional grid) for this fracture network.

Parameters

• mesh_args – Arguments passed on to mesh size control

• tol (double, optional) – Tolerance used for geometric computations. Defaults to the tolerance of this network.

• do_snap (boolean, optional) – Whether to snap lines to avoid small segments. Defaults to True.

• constraints (np.array of int) – Index of network edges that should not generate lower-dimensional meshes, but only act as constraints in the meshing algorithm.

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

• tags_to_transfer (list of key, optional default None) – The tags of the network are passed to the fracture grids.

• remove_small_fractures (bool) – Whether to remove small fractures. FIXME: expand documentation.

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

• 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.

• file_name (Optional[str]) –

Returns

Mixed-dimensional mesh.

Return type

MixedDimensionalGrid

num_frac()

Return the number of fractures stored

orientation(fi=None)

Compute the angle of the fractures to the x-axis.

Parameters

fi (np.array, or int) – Index of fracture(s) where length should be computed. Refers to self.edges

Returns

Orientation of each fracture, relative to the x-axis.

Measured in radians, will be a number between 0 and pi.

Return type

angle

plot(**kwargs)

Plot the fracture set.

The function passes this fracture set to PorePy plot_fractures

Parameters

**kwargs – Keyword arguments to be passed on to matplotlib.

prepare_for_gmsh(mesh_args, tol=None, do_snap=True, constraints=None, dfn=False, remove_small_fractures=False)

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) – Arguments passed on to mesh size control

• tol (double, optional) – Tolerance used for geometric computations. Defaults to the tolerance of this network.

• do_snap (boolean, optional) – Whether to snap lines to avoid small segments. Defaults to True.

• constraints (np.array of int) – Index of network edges that should not generate lower-dimensional meshes, but only act as constraints in the meshing algorithm.

• dfn (boolean, optional) – If True, a DFN mesh (of the network, but not the surrounding matrix) is created. remove_small_fractures Whether to remove small fractures. FIXME: expand documentation.

• remove_small_fractures (bool) –

Returns

Mixed-dimensional mesh.

Return type

MixedDimensionalGrid

snapped_copy(tol)

Modify point definition so that short branches are removed, and almost intersecting fractures become intersecting.

Parameters

tol (double) – Threshold for geometric modifications. Points and segments closer than the threshold may be modified.

Returns

A new network with modified point coordinates.

Return type

FractureNetwork2d

See also

self.copy(), self.copy_with_split_intersections()

start_points(fi=None)

Get start points of all fractures, or a subset.

Parameters

fi (np.array or int, optional) – Index of the fractures for which the start point should be returned. Either a numpy array, or a single int. In case of multiple indices, the points are returned in the order specified in fi. If not specified, all start points will be returned.

Returns

Start coordinates of all fractures.

Return type

np.array, 2 x num_frac

to_csv(file_name, with_header=True)

Save the 2d network on a csv file with comma as separator. Note: the file is overwritten if present. The format is FID, START_X, START_Y, END_X, END_Y

Parameters

file_name

Name of the file.

with_header

Whether to write headers for the five columns in the first row.

Parameters

file_name (str) –

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

Export the fracture network to file.

The file format is given as a 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 lines, 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”.

bounding_box_imposed: bool

Flag indicating whether the bounding box has been imposed.

domain: dict[str, float] | None

The domain for this fracture network.

The domain is defined by a dictionary with keys ‘xmin’, ‘xmax’, ‘ymin’, ‘ymax’. If not specified, the domain will be set to the bounding box of the fractures.

edges

The fractures as an array of start and end points, referring to pts

Additional rows are optional tags of the fractures. In the standard form, the third row (first row of tags) identifies the type of edges, referring to the numbering system in GmshInterfaceTags. The second row of tags keeps track of the numbering of the edges (referring to the original order of the edges) in geometry processing like intersection removal. Additional tags can be assigned by the user.

pts

Start and endpoints of the fractures. Points can be shared by fractures.

tags: dict[int | str, np.ndarray]

Tags for the fractures.

tol

Tolerance used in geometric computations.