dfnGen - C++ Generation Code

dfnGen creates the discrete fracture networks using the feature rejection algorithm for meshing (FRAM). Fractures can be created stochastically or as deterministic features.

The detailed description of FRAM and the implemented methodology is in J. D. Hyman, C. W. Gable, S. L. Painter, and N. Makedonska. Conforming Delaunay triangulation of stochastically generated three dimensional discrete fracture networks: A feature rejection algorithm for meshing strategy. SIAM J. Sci. Comput., 36(4):A1871–A1894, 2014.

Domain Parameters

The following parameters define the domain. All units are in SI (meters for length).

Note

Parameters with (Mandatory) label must be present in python driver script for simulations to run.

domainSize

Description: (Mandatory) Defines the domain size, which is centered at the origin (0,0,0). The first entry is span in x (east/west), the second entry is span in y (North/South), and the third entry is span in z (Top/Bottom).

Type: List of three floats

Default : None

Example:

DFN.parameters['domainSize']['value'] = [10.0,5.0,20.0]
# Create a domain of 10 m by 5 m by 20.
# Minimum/Maximum x is -5/+5
# Minimum/Maximum in y is -2.5/+2.5
# Minimum/Maximum in z is -10/+10.

Note

The minimum and maximum in each direction is 1/2 the input value.

domainSizeIncrease

Description: Temporary domainSize increase for inserting fracture centers outside of the domain defined by domainSize. After generation is complete, the domain is truncated back to domainSize. First entry is expansion in x (east/west), second entry is expansion in y (North/South), and third entry is expansion in z (Top/Bottom). This is used to help mitigate edge density effects.

Type: List of three floats

Default: [0,0,0]

Example:

DFN.params['domainSizeIncrease']['value'] = [2,1,5]
# Increase the domain-size by:
# adding 1 to the +x, and subtracting 1 to the -x
# adding 0.5 to +y, and subtracting -0.5 to -y
# adding 2.5 to +z, and subtracting -2.5 to -z

Note

The domain size increase in each direction must be less than 1/2 the domain size in that direction.

Tip

A good rule of thumb is to set the expansion length to be at least the radius of the largest fracture.

numOfLayers

Description: Defines the number of stratographic layers in the domain. If numOfLayers is 0, then there are no layers. For N layers, there must be N sets of minimum and maximum heights defined in layers. Each stochastic fracture set is assigned to a layer when creating a fracture family (See pydfnGen).

Type: Non-Negative Integer (N > 0)

Default: 0

Example:

DFN.params['numOfLayers']['value'] = 2 # There will be two layers in the domain

layers

Description. Defines the lower and upper limits for each layer. The first layer listed is layer 1, the second is layer 2, etc. Every stochastic families must be assigned to a layer. If the family is assigned to layer 0, then the family in generated through the entire domain.

Type: List of numOfLayers lists with two elements. [zMin, zMax]

Default: None

Example:

DFN.params['layers']['value'] =  [[-50, -30],  # Minimum and Maximum height of layer 1 is -50 m and -30 m
                                    [10, 40]] # Minimum and Maximum height of layer 2 is 10 m and 40 m

Note

First entry (zMin) must be less than second entry (zMax)

Layers can overlap

numOfRegions

Description: Defines the number of cuboid regions in the domain. If numOfRegions is 0, then there are no regions. There must be N sets of defined by regions. Each stochastic fracture set is assigned to a region during fracture family creation (See pydfnGen).

Type: Non-Negative Integer (N > 0)

Default: 0

Example:

DFN.params['numOfRegions']['value'] = 1 # There will be one region in the domain

regions

Description: Defines the bounding box of each region. The first region listed is region 1, the region is region 2, etc. Stochastic families must be assigned to theses regions. If the family is assigned to region 0, then the family in generated through the entire domain.

Type: List of numOfRegions lists with six elements. [minX, maxX, minY, maxY, minZ, maxZ].

Default: None

Example:

DFN.params['regions']['value'] = [[-5, 5, -10, 10, -20, 10],
                                    [0, 10, -5, 15, 10, 20]]
                                    # Will create two regions for sampling
                                    # The first region with
                                    # x-min: -5, x-max: 5
                                    # y-min: -10, y-max: 10
                                    # z-min: -20, z-max: 10

Note

Min/Max values for each direction do not need to be the same.
Minimum value must be less than the maximum value in each direction
Regions can overlap

ignoreBoundaryFaces

Description: Selection of using the boundary faces option.

Type: boolean

False: use boundaryFaces option

True: ignore boundaryFaces option and keep all clusters

Example:

DFN.params['ignoreBoundaryFaces']['value'] = True

Warning

All clusters are retained only if keepOnlyLargestCluster is set to 0.

boundaryFaces

Description: Selects domain boundaries for flow. The generation will only keep clusters of fractures with connections to domain boundaries which are set to 1.

Type: list of six boolean values corresponding to each face of the domain.

boundaryFaces[0] = +X domain boundary

boundaryFaces[1] = -X domain boundary

boundaryFaces[2] = +Y domain boundary

boundaryFaces[3] = -Y domain boundary

boundaryFaces[4] = +Z domain boundary

boundaryFaces[5] = -Z domain boundary

Default: [1,1,0,0,0,0]

Example:

DFN.params['boundaryFaces']['value'] = [1,1,0,0,0,0] # Keep fractures within a cluster that connect the X boundaries

Warning

ignoreBoundaryFaces must be False (default) when using this feature

General Network Generation Parameters

The following parameters define the general network properties.

Note

parameters with (Mandatory) label must be present in python driver script for simulations to run.

stopCondition

Description: Selection criteria for when network generation stops.

Type: boolean (0/1)

Default: 1

0: stop generation once nPoly fractures are accepted

1: stop generation once all fracture family p32 values have been meet

Example:

DFN.params['stopCondition']['value'] = 1

Note

p32 values are defined for each family during the creation of the fracture family. If stopCondition = 0 the famProb of a fracture belonging to a family is set during the creation of the fracture family (See pydfnGen).

nPoly

Description: The total number of fractures requested in the domain. dfnGen will stop generation once there are nPoly number of fractures.

Type: Positive Integer (nPoly > 0)

Default: None

Example:

DFN.params['nPoly']['value'] = 100 # Stop generation once 100 fractures are accepted into the network

Note

Only used if stopCondition is set to 0

famProb

Description: Probability of occurrence for each family of stochastically generated fractures. Values of famProb elements must add up to 1.0. The probabilities are saved in order of families starting with all stochastic ellipses, and then all stochastic rectangles.

Type: List of length number of stochastic fracture families (nFamEll + nFamRect)

This list is automatically generated. The values are defined with the creation of each fracture family (See pydfnGen).

Note

User defined ellipses, rectangles, and polygons are inserted into the domain prior to any stochastic fractures. However, there is a possibility they will be rejected if FRAM constraints are not met.

orientationOption

Description: Selection of fracture family orientation definition.

Type: Value of 0,1,2

: Spherical Coordinates
: Trend / Plunge
: Dip / Strike

This value is set automatically with the definition of fracture families (See pydfnGen).

Note

For spherical coordinates, values are defined using the function parameters theta/phi.
For Trend/Plunge,  values are defined using trend/plunge.
For Dip/Strike, values are defined using dip/strike.

Warning

When using Trend / Plunge or Dip / Strike, angleOption must be set to degree (default), angleOption = ‘degree’

angleOption

Description: Selection of fracture family angle units. All stochastically generated fracture families will use the specified units

Type: String of either ‘degree’ or ‘radian’

Default: ‘degree’

Example:

DFN.params['angleOption']['value'] = 'radian'

Warning

When using Trend / Plunge or Dip / Strike, angleOption must be set to degree (default), angleOption = ‘degree’

h

Description: (Mandatory) Minimum feature size accepted into the network.

Type: Positive float

Note

The following constraints are imposed on h to keep the final mesh size reasonable, unless disableFram is turned on.

h must be greater than  where x,y,z are the elements of domainSize.
h must be smaller than 1/10th the minimum fracture size
h must be larger than 1/1000th than minimum fracture size
h must be non-zero

Default: None

Example:

DFN.params['h']['value'] = .1

Warning

A clear understanding of h is required for network generation and meshing. Refer to J. D. Hyman, C. W. Gable, S. L. Painter, and N. Makedonska. Conforming Delaunay triangulation of stochastically generated three dimensional discrete fracture networks: A feature rejection algorithm for meshing strategy. SIAM J. Sci. Comput., 36(4):A1871–A1894, 2014. for a complete discussion of h.

disableFram

Danger

disableFram: If FRAM is turned off (disableFram: True) the resulting network can only be meshed using the coarse visual mode. You cannot mesh DFN or run flow and transport if the network is generated with disableFram: True.

Description: (Mandatory) Turn FRAM on/off. Having FRAM on is required for full DFN capabilities of meshing, flow, and transport. If FRAM is off then capabilities will be limited.

Type: boolean

False: FRAM is on

True: FRAM is off

Default: False

Example:

DFN.params['disableFram']['value'] = False

Note

disableFram: True and visualizationMode :1 are recommended if the intention is to use an upscaled octree mesh using the UDFM module in pydfnWorks.

printRejectReasons

Description: Option to print rejection information to screen during network generation.

Type: boolean

False: off. Limited rejection information will be printed to screen during generation.

True: on. Detailed fracture information will be printed to screen during generation.

Default: False

Example:

DFN.params['printRejectReasons']['value'] = True

Tip

Turning this feature on is useful for debugging and initial network construction. Having this turned off is more efficient for network generation.

rejectsPerFracture

Description: If fracture is rejected, it will be re-translated to a new position rejectsPerFracture number of times. Increasing this value can help hit distribution targets for stochastic families.

Type: Positive Integer

Default: 10

Example:

DFN.params['rejectsPerFracture']['value'] = 10 # If a fracture is rejected, it will be translated to a new point in the domain 10 times before being completely rejected

Note

Default is 10. Set equal to 1 to ignore.

radiiListIncrease

Description: Increases the length of the radii list in the sampling queue by this percentage. Fracture radii are sampled and ordered (largest to smallest) prior to beginning network generation. If the target distributions are not being properly resolved due to rejection, then increasing this value can help provide a more uniform representation of the distribution. Once the original list is exhausted, then fracture radii are sampled from the distribution at random and only smaller fractures are likely to be accepted.

Type: Positive Double

Default: 0.1

Example:

DFN.params['radiiListIncrease']['value'] = 0.10 # Increase the length of the possible samples by 10%.

Note

Set to 0 to ignore.

Tip

Examine the dfnGen output report to check if the prescribed distributions are being properly resolved. Run DFN.output_report() in the python work file after generation is complete to generate the output report.

visualizationMode

Warning

No longer supported. Selection of visual mode should be done using the pydfnWorks function DFN.mesh_network(visual_mode=True)

Description: Selection if you want to mesh to be coarse, for quick visualization but cannot run flow and transport, or standard mesh.

Type: boolean

False: Create full DFN mesh (full_mesh.inp) for flow and transport

True: Create reduced DFN mesh (reduced_mesh.inp) for quick visualization

Default: False

Example:

DFN.params['visualizationMode']['value'] = False

seed

Description: Seed for random generator. Setting the seed equal to 0 will seed off the clock and a unique network will be produced. Setting the seed equal to a value > 0 will create the same network every time, which is useful for reproducibility.

Type: Non-negative integer

Default: 1

Example:

DFN.params['seed']['value'] = 42069

Tip

If you set seed to 0, the seed used in the generation is saved in the file DFN_output.txt created by dfnGen.

keepOnlyLargestCluster

Description: Selection to retain multiple clusters that connect boundaries or only the largest cluster. The largest cluster is defined by the number of fractures in the cluster.

Type: boolean

False: Keep all clusters that connect the specified boundary faces in boundaryFaces

True: Keep only the largest cluster that connects the specified boundary faces in boundaryFaces

Default: True

Example:

DFN.params['keepOnlyLargestCluster']['value'] = False

keepIsolatedFractures

Description: Selection to keep isolated fractures in the domain after generation is complete.

Type: boolean

False: Remove isolated fractures from the domain

True: Keep isolated in the domain.

Default: False

Example:

DFN.params['keepIsolatedFractures']['value'] = False

Note

Isolated fractures do not contribute to flow in the DFN as they are not connected to flow boundaries. If you are running a DFN, keepIsolatedFractures should be set to False. You can keep isolated fractures in the domain for UDFM meshing.

Danger

Full DFN-meshing will fail if isolated fractures are not removed. Reduced meshing for visualization can still be performed.

tripleIntersections

Description: Selection of whether triple intersection are accepted into the network.

Type: boolean

False: Reject all triple intersections

True: Accept triple intersections that meet FRAM criteria.

Default: False

Example:

DFN.params['tripleIntersections']['value'] = True

Note

Even if tripleIntersections = True, triple intersections can be rejected if they create a feature on the network smaller than h.

Warning

dfnTrans does not support triple intersections.

removeFracturesLessThan

Description: All fractures with radius less than removeFracturesLessThan are removed from the network after generation is complete.

Type: Non-Negative double

Default: 0

Example:

DFN.params['removeFracturesLessThan']['value'] = 5 # Remove all fracture with radius less than 5 meters.

Note

The lower cutoff of fracture size is defined using fracture family generation, e.g., emin for ellipses sampled from a truncated powerlaw. If this parameter is non-zero, then the network will be generated with fractures down to the lower cutoff, but only those with a radius greater than removeFracturesLessThan will be output for meshing.

insertUserRectanglesFirst

Description: Select order for how user defined rectangles and user defined ellipses are inserted into the domain.

Type: boolean

False: Insert user defined ellipses first

True: Insert user defined rectangles first

Default: True

Example:

DFN.params['insertUserRectanglesFirst']['value'] = False

Note

User defined fractures (ellipses, rectangles, and polygons) are always inserted prior to stochastic fractures.

forceLargeFractures

Description: Insert the largest fracture from each family into the domain prior to sampling sequential from family based on their respective probabilities.

Type: boolean

False: Do not force the largest fractures

True: Force the largest fractures

Default: False

DFN.params['forceLargeFractures']['value'] = True

Warning

No Longer Supported. Fractures are sorted by size prior to being inserted into the domain. Larger fractures are inserted first to minimize rejections.

General Network Output Parameters

outputAllRadii

Description: Create an output file of all fracture radii, both accepted and rejected fractures.

Filename: radii_AllAccepted.dat

Format: xRadius yRadius Distribution # (-2 = userPolygon, -1 = userRectangle, 0 = userEllipse, > 0 is family in order of famProb)

Type: boolean

False: Do not create file

True: Create file

Default: False

Example

DFN.params['outputAllRadii']['value'] = False

outputAcceptedRadiiPerFamily

Description: Create one file that contains the radius of every fracture per family prior to isolated fractures removed.

Filename: radii/radii_AllAccepted_Fam_1.dat

Format: xRadius yRadius DistributionNumber (-2 = userPolygon, -1 = userRectangle, 0 = userEllipse, > 0 is family in order of famProb)

Type: boolean

False: Do not create file

True: Create file

Default: False

Example:

DFN.params['outputAcceptedRadiiPerFamily']['value'] = False

outputFinalRadiiPerFamily

Description: Create one file that contains the radius of every fracture per family after to isolated fractures removed.

Filename: radii/radii_Final_Fam_1.dat

Format: xRadius yRadius DistributionNumber (-2 = userPolygon, -1 = userRectangle, 0 = userEllipse, > 0 is family in order of famProb)

Type: boolean

False: Do not create file

True: Create file

Default: False

Example:

DFN.params['outputFinalRadiiPerFamily']['value'] = False

Fracture Family Generation Parameters: Ellipse

This section describes generation parameters for families of disc-shaped fractures. The number of elements in each parameter matches the number of ellipse families in nFamEll. The index of the elements corresponds to the fracture family. The first element of each parameter corresponds to the first family, the second element corresponds to the second family, etc.

Warning

The parameters shown in this section are automatically written to the parameter dictionary (DFN.params) when defining fracture families. Documentation here is meant to provide additional information on the definition of each parameter in the parameter dictionary. For information on setting these parameters see pydfnGen

Ellipse: General Parameters

nFamEll

Description: Number of ellipse families

Type: Non-Negative Integer

Default: 0

Example:

DFN.params['nFamEll']['value'] = 3 # There will be 3 ellipse families

eLayer

Description: Assign each ellipse family to a layer in domain.

Type: list of nFamEll integers

Example:

DFN.params['eLayer']['value'] = [0,2,1]
# Family 1 is assigned to the whole domain
# Family 2 is assigned to layer 2
# Family 3 is assigned to layer 1

Note

Layer 0 is the entire domain. Numbers > 0 correspond to those defined in layers.

Warning

Families can only be assigned to either a layer or a region, not both.

eRegion

Description: Assign each ellipse family to a region in domain.

Type: list of nFamEll integers

Example:

DFN.params['eRegion']['value'] = [0,2,1]
# Family 1 is assigned to the whole domain
# Family 2 is assigned to region 2
# Family 3 is assigned to region 1

Note

Region 0 is the entire domain. Numbers > 0 correspond to those defined in regions.

Warning

Families can only be assigned to either a layer or a region, not both.

e_p32Targets

Description: Target fracture intensity per family. Fracture intensity $P_{32} [\text{m}^{-1}]$ is defined as total surface area of each fracture family divided by the total domain volume. Fractures from each family are inserted into the domain until provided target values are obtained. Generation stops once all desired fracture intensity are obtained.

Type: list of nFamEll floats

Example:

DFN.params['e_p32Targets']['value'] = [0.02,0.4,0.05]
# Family 1 has a target p32 of 0.02
# Family 2 has a target p32 of 0.4
# Family 3 has a target p32 of 0.05

Note

Only used when stopCondition = 1

Warning

The fracture surface area is defined using both sides of a fracture.

enumPoints

Description: Number of vertices defining the boundary of each elliptical fracture

Type: list of nFamEll integers

Example:

DFN.params['enumPoints']['value'] = [8,12,16]
# Fractures from family 1 are defined using 8 points
# Fractures from family 2 are defined using 12 points
# Fractures from family 3 are defined using 16 points

Note

Values must be greater than 4, which corresponds to a rectangle
Increasing this value lead to more challenging acceptance criteria via FRAM due to smaller edge lengths between vertices on the fracture boundary
Suggested value: 8

easpect

Description: Aspect ratio of fractures

Type: list of nFamEll floats

Example:

DFN.params['easpect']['value'] = [1,2,0.5]
# Family 1 has an aspect ratio of 1 (circles)
# Family 2 has an aspect ratio of 2 - y radius is twice the x radius
# Family 3 has an aspect ratio of 0.5 - y radius is 1/2 the x radius

Note

A value of 1 makes circles

Tip

As the aspect ratio increases, the shape of the ellipse can degrade accuracy unless enumPoints is also increased

Ellipse: Fracture Orientation

The fracture orientations are sampled from the three-dimensional von Mises-Fisher distribution,

$f({\bf x}; {\boldsymbol \mu}, \kappa ) = \frac{ \kappa \exp( \kappa {\boldsymbol \mu}^{T} {\bf x} )}{ 4 \pi \sinh(\kappa)}~.$

where ${\boldsymbol \mu}$ is the mean orientation vector and $T$ denotes transpose. The distribution is sampled using the algorithm provided Simulation of the von Mises Fisher distribution Communications in statistics-simulation and computation 23.1 (1994): 157-164. by Andrew Wood..

dfnGen accepts spherical coordinates ( $\theta$ / $\phi$ ), Trend/Plunge, or Dip/Strike to define the mean orientation of a fracture family.

Tip

orientationOption indicates which of these options are used. This is automatically set based on which option is used during fracture family parameter generation. The same option must be used for all families.

: Spherical Coordinate (Theta/Phi)
: Trend / Plunge
: Dip / Strike.

ekappa

Description: The concentration parameter of the von Mises-Fisher distribution, which determines the degree of clustering around the mean orientation.

Type: list of nFamEll floats

Example:

DFN.params['ekappa']['value'] = [0.1, 20, 17]
# Fracture Family 1 has a theta value of 45 degrees
# Fracture Family 2 has a theta value of 78 degrees
# Fracture Family 3 has a theta value of 0 degrees

Note

Values of $\kappa$ approaching zero result in a uniform distribution of points on the sphere. Larger values create points with a small deviation from mean direction.

Warning

The numerical method for sampling the von Mises-Fisher distribution becomes unstable for values greater than 100.

Ellipse: Spherical Coordinates

The mean normal vector of the fracture family $\vec{n}$ is related to the spherical coordinates $\theta$ and $\phi$ by

$\vec{n}_x & = \sin(\theta) \cos(\phi)\\$

$\vec{n}_y & = \sin(\theta) \sin(\phi)\\$

$\vec{n}_z & = \cos(\theta)$

etheta

Description: Angle the normal vector of the fracture makes with the z-axis

Type: list of nFamEll floats

Example:

DFN.params['etheta']['value'] = [45, 78, 0]
# Fracture Family 1 has a theta value of 45 degrees
# Fracture Family 2 has a theta value of 78 degrees
# Fracture Family 3 has a theta value of 0 degrees

Note

Both radians and degrees are supported. Use angleOption to select one. If angleOption is set to radians angleOption = ‘radian’, and the value provided must be less than $2 \pi$ .

ephi

Description: Angle that the projection of the normal vector of a fracture onto the x-y plane makes with the x-axis.

Type: list of nFamEll float

Example:

DFN.params['ephi']['value'] =  [0, 56, 12]
# Fracture Family 1 has a phi value of 0 degrees
# Fracture Family 2 has a phi value of 56 degrees
# Fracture Family 3 has a phi value of 12 degrees

Note

Both radians and degrees are supported. Use angleOption to select one. If angleOption is set to radians angleOption = ‘radian’, then the value provided must be less than $2 \pi$ .

Ellipse: Trend & Plunge

The mean normal vector of the fracture family $\vec{n}$ is related to trend and plunge by

$\vec{n}_x & = \cos(\text{trend}) \cos(\text{plunge})\\$

$\vec{n}_y & = \sin(\text{trend}) \cos(\text{plunge})\\$

$\vec{n}_z & = \sin(\text{trend})$

etrend

Description: Trend of fracture families

Type: list of nFamEll float

Example

DFN.params['etrend']['value'] = [0, 56, 12]
# Fracture Family 1 has a trend value of 0 degrees
# Fracture Family 2 has a trend value of 56 degrees
# Fracture Family 3 has a trend value of 12 degrees

Note

angleOption must be set to degree (angleOption = ‘degree’) to use Trend & Plunge

eplunge

Description: Plunge of fracture families

Type: list of nFamEll float

Example

DFN.params['eplunge']['value'] = [0, 56, 12]
# Fracture Family 1 has a plunge value of 0 degrees
# Fracture Family 2 has a plunge value of 56 degrees
# Fracture Family 3 has a plunge value of 12 degrees

Note

angleOption must be set to degree (angleOption = ‘degree’) to use Trend & Plunge

Ellipse: Dip & Strike

The mean normal vector of the fracture family $\vec{n}$ is related to dip and strike by

$\vec{n}_x & = \sin(\text{dip}) \sin(\text{strike})\\$

$\vec{n}_y & = -\sin(\text{dip}) \cos(\text{strike})\\$

$\vec{n}_z & = \cos(\text{dip})$

estrike

Description: Strike of fracture families

Type: list of nFamEll float

Example

DFN.params['estrike']['value'] = [0, 56, 12]
# Fracture Family 1 has a strike value of 0 degrees
# Fracture Family 2 has a strike value of 56 degrees
# Fracture Family 3 has a strike value of 12 degrees

Note

angleOption must be set to degree (angleOption = ‘degree’) to use Dip & Strike

edip

Description: Dip of fracture families

Type: list of nFamEll float

Example

DFN.params['edip']['value'] = [0, 56, 12]
# Fracture Family 1 has a dip value of 0 degrees
# Fracture Family 2 has a dip value of 56 degrees
# Fracture Family 3 has a dip value of 12 degrees

Note

angleOption must be set to degree (angleOption = ‘degree’) to use Dip & Strike

Ellipse: In Plane Rotation

ebetaDistribution

Description: Prescribe a rotation around each fracture’s normal vector, with the fracture centered on x-y plane at the origin

Type: list of nFamEll boolean values

0: Uniform distribution on [0, $2 \pi$ )

1: Constant rotation specified by ebeta

DFN.params['ebetaDistribution']['value'] = [0, 1, 1]
# Fracture Family 1 will have a random rotation
# Fracture Family 2 will have a constant angle of rotation defined in the first entry of ebeta
# Fracture Family 3 will have a constant angle of rotation defined in the second entry of ebeta

ebeta

Description: Values for constant angle of rotation around the normal vector

Type: list of boolean (0/1)

Example:

DFN.params['ebetaDistribution']['value'] = [45, 270] # For ebetaDistribution: [0, 1, 1]
# Fracture Family 2 will have a constant angle of rotation of 45 degrees
# Fracture Family 3 will have a constant angle of rotation of 270 degrees

Note

1. The length of ebeta corresponds to the number of non-zero entries in ebetaDistribution

2. angleOption defines if the values are in radians or degrees

Ellipse: Fracture Radius Distributions

Fracture radii can be defined using four different distributions: (1) Log-Normal, (2) Truncated Power-law, (3) Exponential, and (4) Constant. Minimum and maximum values must be provided for 1-3 along with the distribution parameters.

edistr

Description: Assigns fracture radius distribution for each family

Type: list of nFamEll Integers (1,2,3,4)

Example:

DFN.params['edistr']['value'] = [1, 2, 4]
# Fracture Family 1 will use a LogNormal Distribution
# Fracture Family 2 will use a Truncated powerlaw distribution
# Fracture Family 3 will have a constant sized fractures

Note

Number of elements in the parameters for each distribution must match number of families assigned to that distribution.

Ellipse: Lognormal Distribution

Fracture radii are sampled from a Lognormal distribution with the following probability density function

$\frac{1}{x \sigma \sqrt{2\pi}} \exp \left (- \frac{(\ln x -\mu)^2}{2 \sigma^2} \right)$

with mean $\mu$ and variance $\sigma^2$ .

Warning

dfnGen uses the mean and standard deviation of the underlying normal distribution that creates the lognormal distribution not the mean and variance of the lognormal distribution.

In order to produce a LogNormal distribution with a desired mean ( $\mu$ ) and variance ( $\sigma^2$ ) one uses

$eLogMean = \ln \left ( \frac{\mu^2}{\sqrt{\mu^2 + \sigma^2}} \right)$

and

$esd = \sqrt{\ln \left ( 1 + \frac{ \sigma^2}{\mu^2} \right )}$

For more details see https://en.wikipedia.org/wiki/Log-normal_distribution.

eLogMean

Warning

This value is not the mean of the Log Normal distribution. Use the equations above to convert between the values if needed.

Description: Mean value of the underlying normal distribution

Type: list of float. Length is the number of elements in edistr set to 1.

Example:

DFN.params['eLogMean']['value'] = [1.609] # This value along with that in esd produce a lognormal with mean 5 m and variance of 0.1

esd

Warning

This value is not the standard deviation of the Log Normal distribution. Use the equations above to convert between the values if needed.

Description: Standard deviation value of the underlying normal distribution

Type: list of Positive floats. Length is the number of elements in edistr set to 1.

Example:

DFN.params['esd']['value'] = [0.040] # This value along with that in eLogMean produce a lognormal with mean 5 m and variance of 0.1

eLogMin

Description: Minimum radius created by the LogNormal distribution for each family

Type: list of Positive floats. Length is the number of elements in edistr set to 1.

Example:

DFN.params['eLogMin']['value'] = [1,0.4]
# Lognormal family 1 has a minimum radius of 1 m
# Lognormal family 2 has a maximum radius of 0.4 m

Note

eLogMin must be less than eLogMax within each family.

eLogMax

Description: Maximum radius created by the LogNormal distribution for each family

Type: list of Positive floats. Length is the number of elements in edistr set to 1.

Example:

DFN.params['eLogMax']['value'] = [10,12]
# Lognormal family 1 has a maximum radius of 10 m
# Lognormal family 2 has a maximum radius of 12 m

Note

eLogMax must be greater than eLogMin within each family.

Ellipse: Truncated Powerlaw Distribution

Fracture radii are sampled from a truncated power-law distribution with lower bound $r_0$ , upper bound $r_u$ , and exponent $\alpha$ defined by the following probability density function

$\frac{\alpha}{r_0} \frac{(r/r_0)^{-1-\alpha}}{1 - (r_u/r_0)^{-\alpha}}.$

ealpha

Description: Exponent of the truncated powerlaw distribution

Type: list of Positive floats. Length is the number of elements in edistr set to 2.

Example:

DFN.params['ealpha']['value'] = [1.6, 2.2]
# TPL family 1 has an alpha of 1.6
# TPL family 2 has an alpha of 2.2

Note

A value of 0 creates constant sized fractures of size emin

emin

Description: Lower cutoff of the truncated powerlaw distribution

Type: list of Positive floats. Length is the number of elements in edistr set to 2.

Example:

DFN.params['emin']['value'] = [1.2, 5]
# TPL family 1 has an lower cutoff of 1.2 m
# TPL family 2 has an lower cutoff of 5 m

Note

emin must be less than emax within each family.

emax

Description: Upper cutoff of the truncated powerlaw distribution

Type: list of Positive floats. Length is the number of elements in edistr set to 2.

Example:

DFN.params['emax']['value'] = [10, 50]
# TPL family 1 has an upper cutoff of 10 m
# TPL family 2 has an upper cutoff of 50 m

Note

emax must be greater than emin within each family.

Ellipse: Exponential Distribution

Fracture radii are sampled from a exponential distribution with the following probability density function

$\lambda e^{-\lambda x}$

Where $\lambda$ is referred to as the rate parameter.

eExpMean

Description: Mean value of each exponential distribution

Type: list of Positive floats. Length is the number of elements in edistr set to 3.

Example:

DFN.params['eExpMean']['value'] = [10, 25]
# Exponential family 1 has a mean value of 10 m
# Exponential family 2 has a mean value of 25 m

Note

eExpMean equal to $1/\lambda$ where $\lambda$ is the rate parameter of the distribution.

eExpMin

Description: Lower cutoff of the exponential distribution families

Type: list of Positive floats. Length is the number of elements in edistr set to 3.

Example:

DFN.params['eExpMin']['value'] = [1, 7]
# Exponential family 1 has a lower cutoff value of 1 m
# Exponential family 2 has a lower cutoff value of 7 m

Note

eExpMin must be less than eExpMax within each family.

eExpMax

Description: Upper cutoff of the exponential distribution families

Type: list of Positive floats. Length is the number of elements in edistr set to 3.

Example:

DFN.params['eExpMax']['value'] = [527, 89]
# Exponential family 1 has a upper cutoff value of 527 m
# Exponential family 2 has a upper cutoff value of 89 m

Note

eExpMax must be greater than eExpMin within each family.

Ellipse: Constant

Constant sized fracture families are defined using a single parameter econst. These families are also referred to as uniform or mono-disperse.

econst

Description: Constant radius for each family

Type: list of Positive floats. Length is the number of elements in edistr set to 4.

Example:

DFN.params['econst']['value'] = [1, 7]
# Constant family 1 has a x-radius of 1 m
# Constant family 2 has a x-radius of 7 m

Fracture Family Generation Parameters: Rectangle

This section describes generation parameters for families of rectangular fractures. The number of elements in each parameter matches the number of rectangle families in nFamRect. The index of the elements corresponds to the fracture family. The first element of each parameter corresponds to the first family, the second element corresponds to the second family, etc.

Warning

The parameters shown in this section are automatically written to the parameter dictionary (DFN.params) when defining fracture families. Documentation here is meant to provide additional information on the definition of each parameter in the parameter dictionary. For information on setting these parameters see pydfnGen

Rectangle: General Parameters

nFamRect

Description: Number of rectangle families

Type: Non-Negative Integer

Default: 0

Example:

DFN.params['nFamRect']['value'] = 3 # There will be 3 rectangle families

rLayer

Description: Assign each rectangle family to a layer in domain.

Type: list of nFamRect integers

Example:

DFN.params['rLayer']['value'] = [0,2,1]
# Family 1 is assigned to the whole domain
# Family 2 is assigned to layer 2
# Family 3 is assigned to layer 1

Note

Layer 0 is the entire domain. Numbers > 0 correspond to those defined in layers.

Warning

Families can only be assigned to either a layer or a region, not both.

rRegion

Description: Assign each rectangle family to a region in domain.

Type: list of nFamRect integers

Example:

DFN.params['rRegion']['value'] = [0,2,1]
# Family 1 is assigned to the whole domain
# Family 2 is assigned to region 2
# Family 3 is assigned to region 1

Note

Region 0 is the entire domain. Numbers > 0 correspond to those defined in regions.

Warning

Families can only be assigned to either a layer or a region, not both.

r_p32Targets

Description: Target fracture intensity per family. Fracture intensity $P_{32} [\text{m}^{-1}]$ is defined as total surface area of each fracture family divided by the total domain volume. Fractures from each family are inserted into the domain until provided target values are obtained. Generation stops once all desired fracture intensity are obtained.

Type: list of nFamRect floats

Example:

DFN.params['r_p32Targets']['value'] = [0.02,0.4,0.05]
# Family 1 has a target p32 of 0.02
# Family 2 has a target p32 of 0.4
# Family 3 has a target p32 of 0.05

Note

Only used when stopCondition = 1

Warning

The fracture surface area is defined using both sides of a fracture.

raspect

Description: Aspect ratio of fractures

Type: list of nFamRect floats

Example:

DFN.params['raspect']['value'] = [1,2,0.5]
# Family 1 has an aspect ratio of 1 (circles)
# Family 2 has an aspect ratio of 2 - y radius is twice the x radius
# Family 3 has an aspect ratio of 0.5 - y radius is 1/2 the x radius

Note

A value of 1 makes squares

Rectangle: Fracture Orientation

The fracture orientations are sampled from the three-dimensional von Mises-Fisher distribution,

$f({\bf x}; {\boldsymbol \mu}, \kappa ) = \frac{ \kappa \exp( \kappa {\boldsymbol \mu}^{T} {\bf x} )}{ 4 \pi \sinh(\kappa)}~.$

where ${\boldsymbol \mu}$ is the mean orientation vector and $T$ denotes transpose. The distribution is sampled using the algorithm provided Simulation of the von Mises Fisher distribution Communications in statistics-simulation and computation 23.1 (1994): 157-164. by Andrew Wood..

dfnGen accepts spherical coordinates ( $\theta$ / $\phi$ ), Trend/Plunge, or Dip/Strike to define the mean orientation of a fracture family.

Tip

orientationOption indicates which of these options are used. This is automatically set based on which option is used during fracture family parameter generation. The same option must be used for all families.

: Spherical Coordinate (Theta/Phi)
: Trend / Plunge
: Dip / Strike.

rkappa

Description: The concentration parameter of the von Mises-Fisher distribution, which determines the degree of clustering around the mean orientation.

Type: list of nFamRect floats

Example:

DFN.params['rkappa']['value'] = [0.1, 20, 17]
# Fracture Family 1 has a theta value of 45 degrees
# Fracture Family 2 has a theta value of 78 degrees
# Fracture Family 3 has a theta value of 0 degrees

Note

Values of $\kappa$ approaching zero result in a uniform distribution of points on the sphere. Larger values create points with a small deviation from mean direction.

Warning

The numerical method for sampling the von Mises-Fisher distribution becomes unstable for values greater than 100.

Rectangle: Spherical Coordinates

The mean normal vector of the fracture family $\vec{n}$ is related to the spherical coordinates $\theta$ and $\phi$ by

$\vec{n}_x & = \sin(\theta) \cos(\phi)\\$

$\vec{n}_y & = \sin(\theta) \sin(\phi)\\$

$\vec{n}_z & = \cos(\theta)$

rtheta

Description: Angle the normal vector of the fracture makes with the z-axis

Type: list of nFamRect floats

Example:

DFN.params['rtheta']['value'] = [45, 78, 0]
# Fracture Family 1 has a theta value of 45 degrees
# Fracture Family 2 has a theta value of 78 degrees
# Fracture Family 3 has a theta value of 0 degrees

Note

Both radians and degrees are supported. Use angleOption to select one. If angleOption is set to radians angleOption = ‘radian’, and the value provided must be less than $2 \pi$ .

rphi

Description: Angle that the projection of the normal vector of a fracture onto the x-y plane makes with the x-axis.

Type: list of nFamRect float

Example:

DFN.params['rphi']['value'] =  [0, 56, 12]
# Fracture Family 1 has a phi value of 0 degrees
# Fracture Family 2 has a phi value of 56 degrees
# Fracture Family 3 has a phi value of 12 degrees

Note

Both radians and degrees are supported. Use angleOption to select one. If angleOption is set to radians angleOption = ‘radian’, then the value provided must be less than $2 \pi$ .

Rectangle: Trend & Plunge

The mean normal vector of the fracture family $\vec{n}$ is related to trend and plunge by

$\vec{n}_x & = \cos(\text{trend}) \cos(\text{plunge})\\$

$\vec{n}_y & = \sin(\text{trend}) \cos(\text{plunge})\\$

$\vec{n}_z & = \sin(\text{trend})$

rtrend

Description: Trend of fracture families

Type: list of nFamRect float

Example

DFN.params['rtrend']['value'] = [0, 56, 12]
# Fracture Family 1 has a trend value of 0 degrees
# Fracture Family 2 has a trend value of 56 degrees
# Fracture Family 3 has a trend value of 12 degrees

Note

angleOption must be set to degree (angleOption = ‘degree’) to use Trend & Plunge

rplunge

Description: Plunge of fracture families

Type: list of nFamRect float

Example

DFN.params['rplunge']['value'] = [0, 56, 12]
# Fracture Family 1 has a plunge value of 0 degrees
# Fracture Family 2 has a plunge value of 56 degrees
# Fracture Family 3 has a plunge value of 12 degrees

Note

angleOption must be set to degree (angleOption = ‘degree’) to use Trend & Plunge

Rectangle: Dip & Strike

The mean normal vector of the fracture family $\vec{n}$ is related to dip and strike by

$\vec{n}_x & = \sin(\text{dip}) \sin(\text{strike})\\$

$\vec{n}_y & = -\sin(\text{dip}) \cos(\text{strike})\\$

$\vec{n}_z & = \cos(\text{dip})$

rstrike

Description: Strike of fracture families

Type: list of nFamRect float

Example

DFN.params['rstrike']['value'] = [0, 56, 12]
# Fracture Family 1 has a strike value of 0 degrees
# Fracture Family 2 has a strike value of 56 degrees
# Fracture Family 3 has a strike value of 12 degrees

Note

angleOption must be set to degree (angleOption = ‘degree’) to use Dip & Strike

rdip

Description: Dip of fracture families

Type: list of nFamRect float

Example

DFN.params['rdip']['value'] = [0, 56, 12]
# Fracture Family 1 has a dip value of 0 degrees
# Fracture Family 2 has a dip value of 56 degrees
# Fracture Family 3 has a dip value of 12 degrees

Note

angleOption must be set to degree (angleOption = ‘degree’) to use Dip & Strike

Rectangle: In Plane Rotation

rbetaDistribution

Description: Prescribe a rotation around each fracture’s normal vector, with the fracture centered on x-y plane at the origin

Type: list of nFamRect boolean values

0: Uniform distribution on [0, $2 \pi$ )

1: Constant rotation specified by rbeta

DFN.params['rbetaDistribution']['value'] = [0, 1, 1]
# Fracture Family 1 will have a random rotation
# Fracture Family 2 will have a constant angle of rotation defined in the first entry of ebeta
# Fracture Family 3 will have a constant angle of rotation defined in the second entry of ebeta

rbeta

Description: Values for constant angle of rotation around the normal vector

Type: list of boolean (0/1)

Example:

DFN.params['rbetaDistribution']['value'] = [45, 270] # For ebetaDistribution: [0, 1, 1]
# Fracture Family 2 will have a constant angle of rotation of 45 degrees
# Fracture Family 3 will have a constant angle of rotation of 270 degrees

Note

1. The length of rbeta corresponds to the number of non-zero entries in rbetaDistribution

2. :ref: angleOption defines if the values are in radians or degrees

Rectangle: Fracture Radius Distributions

Fracture radii can be defined using four different distributions: (1) Log-Normal, (2) Truncated Power-law, (3) Exponential, and (4) Constant. Minimum and maximum values must be provided for 1-3 along with the distribution parameters.

rdistr

Description: Assigns fracture radius distribution for each family

Type: list of nFamRect Integers (1,2,3,4)

Example:

DFN.params['rdistr']['value'] = [1, 2, 4]
# Fracture Family 1 will use a LogNormal Distribution
# Fracture Family 2 will use a Truncated powerlaw distribution
# Fracture Family 3 will have a constant sized fractures

Note

Number of elements in the parameters for each distribution must match number of families assigned to that distribution.

Rectangle: Lognormal Distribution

Fracture radii are sampled from a Lognormal distribution with the following probability density function

$\frac{1}{x \sigma \sqrt{2\pi}} \exp \left (- \frac{(\ln x -\mu)^2}{2 \sigma^2} \right)$

with mean $\mu$ and variance $\sigma^2$ .

Warning

dfnGen uses the mean and standard deviation of the underlying normal distribution that creates the lognormal distribution not the mean and variance of the lognormal distribution.

In order to produce a LogNormal distribution with a desired mean ( $\mu$ ) and variance ( $\sigma^2$ ) one uses

$eLogMean = \ln \left ( \frac{\mu^2}{\sqrt{\mu^2 + \sigma^2}} \right)$

and

$esd = \sqrt{\ln \left ( 1 + \frac{ \sigma^2}{\mu^2} \right )}$

For more details see https://en.wikipedia.org/wiki/Log-normal_distribution.

rLogMean

Warning

This value is not the mean of the Log Normal distribution. Use the equations above to convert between the values if needed.

Description: Mean value of the underlying normal distribution

Type: list of float. Length is the number of elements in rdistr set to 1.

Example:

DFN.params['rLogMean']['value'] = [1.609] # This value along with that in esd produce a lognormal with mean 5 m and variance of 0.1

rsd

Warning

This value is not the standard deviation of the Log Normal distribution. Use the equations above to convert between the values if needed.

Description: Standard deviation value of the underlying normal distribution

Type: list of Positive floats. Length is the number of elements in rdistr set to 1.

Example:

DFN.params['rsd']['value'] = [0.040] # This value along with that in rLogMean produce a lognormal with mean 5 m and variance of 0.1

rLogMin

Description: Minimum radius created by the LogNormal distribution for each family

Type: list of Positive floats. Length is the number of elements in rdistr set to 1.

Example:

DFN.params['rLogMin']['value'] = [1,0.4]
# Lognormal family 1 has a minimum radius of 1 m
# Lognormal family 2 has a maximum radius of 0.4 m

Note

rLogMin must be less than rLogMax within each family.

rLogMax

Description: Maximum radius created by the LogNormal distribution for each family

Type: list of Positive floats. Length is the number of elements in rdistr set to 1.

Example:

DFN.params['rLogMax']['value'] = [10,12]
# Lognormal family 1 has a maximum radius of 10 m
# Lognormal family 2 has a maximum radius of 12 m

Note

rLogMax must be greater than rLogMin within each family.

Rectangle: Truncated Powerlaw Distribution

Fracture radii are sampled from a truncated power-law distribution with lower bound $r_0$ , upper bound $r_u$ , and exponent $\alpha$ defined by the following probability density function

$\frac{\alpha}{r_0} \frac{(r/r_0)^{-1-\alpha}}{1 - (r_u/r_0)^{-\alpha}}.$

ralpha

Description: Exponent of the truncated powerlaw distribution

Type: list of Positive floats. Length is the number of elements in rdistr set to 2.

Example:

DFN.params['ralpha']['value'] = [1.6, 2.2]
# TPL family 1 has an alpha of 1.6
# TPL family 2 has an alpha of 2.2

Note

A value of 0 creates constant sized fractures of size rmin

rmin

Description: Lower cutoff of the truncated powerlaw distribution

Type: list of Positive floats. Length is the number of elements in rdistr set to 2.

Example:

DFN.params['rmin']['value'] = [1.2, 5]
# TPL family 1 has an lower cutoff of 1.2 m
# TPL family 2 has an lower cutoff of 5 m

Note

rmin must be less than rmax within each family.

rmax

Description: Upper cutoff of the truncated powerlaw distribution

Type: list of Positive floats. Length is the number of elements in rdistr set to 2.

Example:

DFN.params['rmax']['value'] = [10, 50]
# TPL family 1 has an upper cutoff of 10 m
# TPL family 2 has an upper cutoff of 50 m

Note

rmax must be greater than rmin within each family.

Rectangle: Exponential Distribution

Fracture radii are sampled from a exponential distribution with the following probability density function

$\lambda e^{-\lambda x}$

Where $\lambda$ is referred to as the rate parameter.

rExpMean

Description: Mean value of each exponential distribution

Type: list of Positive floats. Length is the number of elements in rdistr set to 3.

Example:

DFN.params['rExpMean']['value'] = [10, 25]
# Exponential family 1 has a mean value of 10 m
# Exponential family 2 has a mean value of 25 m

Note

rExpMean equal to $1/\lambda$ where $\lambda$ is the rate parameter of the distribution.

rExpMin

Description: Lower cutoff of the exponential distribution families

Type: list of Positive floats. Length is the number of elements in rdistr set to 3.

Example:

DFN.params['rExpMin']['value'] = [1, 7]
# Exponential family 1 has a lower cutoff value of 1 m
# Exponential family 2 has a lower cutoff value of 7 m

Note

rExpMin must be less than rExpMax within each family.

rExpMax

Description: Upper cutoff of the exponential distribution families

Type: list of Positive floats. Length is the number of elements in rdistr set to 3.

Example:

DFN.params['rExpMax']['value'] = [527, 89]
# Exponential family 1 has a upper cutoff value of 527 m
# Exponential family 2 has a upper cutoff value of 89 m

Note

rExpMax must be greater than rExpMin within each family.

Rectangle: Constant

Constant sized fracture families are defined using a single parameter rconst. These families are also referred to as uniform or mono-disperse.

rconst

Description: Constant radius for each family

Type: list of Positive floats. Length is the number of elements in rdistr set to 4.

Example:

DFN.params['rconst']['value'] = [1, 7]
# Constant family 1 has a x-radius of 1 m
# Constant family 2 has a x-radius of 7 m

User Defined Fracture Generation Parameters

User defined deterministic features can be included into dfnWorks in a number of ways. There are two format options for ellipses and rectangles. One can also put in a selection of convex n vertex polygons.

Note

To incoperate user fractures into the domain see functions add_user_fract and add_user_fract_from_file in pydfnGen. Information in this section provides additional information about parameters as well as information for adding user fractures from a predefined file.

User Defined Ellipses

Ellipses can be included using two different formats: general or coordinates.

userEllipsesOnOff

Description: Selection if general user defined ellipses are going to be used. If this option is activated, then the file UserEll_Input_File_Path is read. The path to that file must be valid.

Type: boolean (0/1)

0: Do not include general user defined ellipses

1: Do include general user defined ellipses

UserEll_Input_File_Path

Description: Filepath for general user defined ellipses.

Type: string

Example:

DFN.params['UserEll_Input_Filepath']['value'] = '/dfnWorks/examples/4_user_ell_uniform/define_4_user_ellipses.dat'

General user defined ellipses parameters

Below are the required parameters for the general user defined ellipses

nUserEll

Description: Number of User Defined Ellipses

Type: Int

Example:

nUserEll: 2 // 2 ellipses are expected in the file

Number_of_Vertices

Description: Number of vertices defining the boundary of each ellipse. One per line per fracture.

Type: Int

Example:

Number_of_Vertices:
12 // fracture 1 has 12 vertices
8 // fracture 2 has 8 vertices

Radii

Description: Radius of each ellipse

Type: Double, one value per line per fracture

Example:

Radii:
0.5 // fracture 1 has a radius of 0.5 m
1 // fracture 1 has a radius of 1 m

Aspect_Ratio

Description: Aspect Ratio for each ellipse

Type: Double, one value per line per fracture

Example:

Aspect_Ratio:
1 // fracture 1 has a radius of 1
2 // fracture 2 has a radius of 2

AngleOption (User Defined Fracture)

Description: Selection of Radius / Degrees

Type: boolean

0: All angles in radians

1: All angles in degrees

Example:

AngleOption:
0 // fracture 1 has angles in radians
1 // fracture 2 has angles in degrees

Beta

Description: Rotation around center for each ellipse (one per line)

Type: Double, one value per line per fracture

Example:

AngleOption:
0 // no rotation for fracture 1
45 // rotate fracture 2 by 45 degrees

Translation

Description: Translation of each ellipse according to its center {x,y,z} (one per line)

Type: Set of double values {x,y,z}

Example:

Translation:
{-0.2,0,0} // Fracture 1 has a center at -0.2, 0, 0
{0,1,0} // Fracture 2 has a center at 0, 1, 0

userOrientationOption

Description: Selection of fracture orientation definition. The same orientation option must be used for all fractures.

0 : Normal Vector -> Normal {x,y,z}

1 : Trend / Plunge

2 : Dip / Strike

Type: Value of 0,1,2

Example:

userOrientationOption: 0 // Fracture orientation will be defined using normal vectors

Note

If option 0 is selected, the keyword normal is required.
If option 1 is selected, the keyword Trend_Plunge is required.
If option 2 is selected, the keyword Dip_Strike is required.

Warning

You cannot mix orientation options

Normal

Description: Normal vector of each ellipse according {x,y,z} (one per line)

Type: Set of double values {x,y,z}

Example:

Normal:
{0,0,1} // Fracture 1 has a normal vector of [0,0,1]
{1,1,0} // Fracture 1 has a normal vector of [1,1,0]

Note

Vectors do not need to be normalized

Trend_Plunge

Description: Trend and plunge for each fracture

Type: Set of double values {trend,plunge}

Example:

Trend_Plunge:
{45, 90} // Fracture 1 has a trend of 45 and plunge of 90
{0, 37} // Fracture 2 has a trend of 0 and plunge of 37

Warning

AngleOption (User Defined Fracture) must be set to degrees

Dip_Strike

Description: Dip and Strike for each fracture

Type: Set of double values {dip,strike}

Example:

Trend_Plunge:
{45, 90} // Fracture 1 has a dip of 45 and strike of 90
{0, 37} // Fracture 2 has a dip of 0 and strike of 37

Warning

AngleOption (User Defined Fracture) must be set to degrees

General Ellipse Input Example

/************************* USER DEFINED ELLIPSES ***************************/
/*****************************************************************************/

/*****************************************************************************/
//Number of User Defined Ellipses
/*****************************************************************************/
nUserEll: 4


/*****************************************************************************/
//Radius for each ellipse (one per line)
/*****************************************************************************/
Radii:
0.5
0.5
0.4
0.4


/*****************************************************************************/
//Aspect Ratio for each ellipse (one per line)
/*****************************************************************************/
Aspect_Ratio:
1
1
1
1


/*****************************************************************************/
//Angle Option: 0 - All angles in radians
//              1 - All angles in degrees
/*****************************************************************************/
AngleOption:
1
1
1
1

/*****************************************************************************/
//Rotation around center for each ellipse (one per line)
/*****************************************************************************/
Beta:
0
0
0
0

/*****************************************************************************/
//Translation of each ellipse according to its center {x,y,z} (one per line)
/*****************************************************************************/
Translation:
{-0.2,0,0}
{0,0,0}
{0.2,0,0.2}
{0.2,0,-0.2}


/*****************************************************************************/
//  userOrientationOption:
//  0 - Normal Vector -> Normal {x,y,z}
//  1 - Trend / Plunge -> Trend_Plunge {trend, plunge} -> Must be degrees
//  2 - Dip / Strike - > Dip_Strike {dip, strike} -> Must be degrees
/*****************************************************************************/

userOrientationOption: 0


/*****************************************************************************/
//Normal Vector for each ellipse (one per line)
/*****************************************************************************/
Normal:
{0,0,1}
{1,0,0}
{0,0,1}
{0,0,1}


Number_of_Vertices:
8
8
8
8

userEllByCoord

Description: Selection if user defined ellipses by coordinate are going to be used. If this option is activated, then the file EllByCoord_Input_File_Path is read. The path to that file must be valid.

Type: boolean (0/1)

0: Do not include user defined ellipses by coordinate

1: Include user defined ellipses by coordinate

Warning

The same number of vertices must be used for all fractures.

EllByCoord_Input_File_Path

Description: File path name for user defined ellipses by coordinate

Type: string

Example:

DFN.params['EllByCoord_Input_File_Path']['value'] = '/dfnWorks/example/4_user_ell/ellCoords.dat'

User defined ellipses by coordinate parameters

Below are the required parameters for the user defined ellipses by coordinate

nEllipses

Description: Number of User Defined Ellipses

Type: Integer

Example:

nEllipses: 2

nNodes

Description: Number of nodes for all ellipses

Type: Integer

nNodes: 5

Coordinates

Description: Coordinates / Vertices for each ellipse.

Type: Set of nNodes triples ${x_0, y_0, z_0} {x_1, y_1, z_1} \ldots {x_n, y_n, z_n}$

Coordinates:
{-2,-1,0} {1,-2,0} {2,0,0} {0,2,0} {-2,1,0}
{0,-0.3,-1} {0,.5,-.7} {0,.7,1} {0,-.7,1} {0,-1,0}

Warning

Coordinates must be listed in clockwise, or counterclockwise order. Coordinates must be co-planar

Ellipse By Coordinate Example

/************************************************************************/
/*                 ELLIPSES SPECIFIED BY COORDINATES                  */
/************************************************************************/
// NOTE: Coordinates must be listed in clockwise, or counterclockwise order
//       Coordinates must be co-planar

/************************************************************************/
// Number of Ellipses Defined
/************************************************************************/

nEllipses: 2


/************************************************************************/
// Number of nodes for all ellipses
/************************************************************************/

nNodes: 5


/************************************************************************/
// Coordinates (4 vertice coordinates per line/One rectangle per line)
/************************************************************************/
// One Ellipse per line (White space and new lines should not matter)
// Format: {x1,y1,z1} {x2,y2,z2} {x3,y3,z3} {x4,y4,z4} ... {xn, yn, zn}

Coordinates:

{-2,-1,0} {1,-2,0} {2,0,0} {0,2,0} {-2,1,0}
{0,-0.3,-1} {0,.5,-.7} {0,.7,1} {0,-.7,1} {0,-1,0}

User Defined Rectangles

Deterministic Rectangles can be included using two different formats: general or coordinates.

userRectanglesOnOff

Description: Selection if general user defined rectangles are going to be used. If this option is activated, then the file UserRect_Input_File_Path is read. The path to that file must be valid.

Type: boolean (0/1)

0: Do not include general user defined rectangles

1: Do include general user defined rectangles

UserRect_Input_File_Path

Description: Filepath for general user defined rectangles

Type: string

Example:

DFN.params['UserRect_Input_File_Path']['value'] = '/dfnWorks/examples/4_user_rects/define_4_user_rects.dat'

General user defined rectangles parameters

Below are the required parameters for the general user defined rectangles

nUserRect

Description: Number of user defined rectangles

Type: Int

Example:

nUserRect: 2 // There will be 2 rectangles expected.

Additional parameters have the same definitions as for user defined ellipses:

Radii
Aspect_Ratio
AngleOption (User Defined Fracture)
Beta
Translation
userOrientationOption
Normal
Trend_Plunge
Dip_Strike

General Rectangle Input Example

/************************* USER DEFINED rectangles ***************************/
/*****************************************************************************/

/*****************************************************************************/
//Number of User Defined rectangles
/*****************************************************************************/
nUserRect: 4


/*****************************************************************************/
//Radius for each rectangle (one per line)
/*****************************************************************************/
Radii:
0.5
0.5
0.4
0.4


/*****************************************************************************/
//Aspect Ratio for each rectangle (one per line)
/*****************************************************************************/
Aspect_Ratio:
1
1
1
1


/*****************************************************************************/
//Angle Option: 0 - All angles in radians
//              1 - All angles in degrees
/*****************************************************************************/
AngleOption:
1
1
1
1

/*****************************************************************************/
//Rotation around center for each rectangle (one per line)
/*****************************************************************************/
Beta:
0
0
0
0

/*****************************************************************************/
//Translation of each rectangle according to its center {x,y,z} (one per line)
/*****************************************************************************/
Translation:
{-0.2,0,0}
{0,0,0}
{0.2,0,0.2}
{0.2,0,-0.2}


/*****************************************************************************/
//  userOrientationOption:
//  0 - Normal Vector -> Normal {x,y,z}
//  1 - Trend / Plunge -> Trend_Plunge {trend, plunge} -> Must be degrees
//  2 - Dip / Strike - > Dip_Strike {dip, strike} -> Must be degrees
/*****************************************************************************/

userOrientationOption: 0


/*****************************************************************************/
//Normal Vector for each rectangle (one per line)
/*****************************************************************************/
Normal:
{0,0,1}
{1,0,0}
{0,0,1}
{0,0,1}

userRecByCoord

Description: Selection if user defined rectangles by coordinate are going to be used. If this option is activated, then the file RectByCoord_Input_File_Path is read. The path to that file must be valid.

Type: boolean (0/1)

0: Do not include user defined rectangles by coordinate

1: include user defined rectangles by coordinate

Warning

The same number of vertices must be used for all fractures.

RectByCoord_Input_File_Path

Description: File path name for user defined rectangles by coordinate

Type: string

Example:

DFN.params['RectByCoord_Input_File_Path']['value'] = '/dfnWorks/example/4_user_rect/rectCoords.dat'

User defined rectangles by coordinate parameters

Below are the required parameters for the user defined rectangles by coordinate

nRectangles

Description: Number of user defined rectangles

Type: Integer

Example:

nRectangles: 2

Fracture coordinates are defined using the same method as for ellipses. See Coordinates.

Rectangle By Coordinate Example

/************************************************************************/
/*                 rectangles SPECIFIED BY COORDINATES                  */
/************************************************************************/
// NOTE: Coordinates must be listed in clockwise, or counterclockwise order
//       Coordinates must be co-planar

/************************************************************************/
// Number of rectangles Defined
/************************************************************************/

nRectangles: 2

/************************************************************************/
// Coordinates (4 vertices coordinates per line/One rectangle per line)
/************************************************************************/
// One rectangle per line (White space and new lines should not matter)
// Format: {x1,y1,z1} {x2,y2,z2} {x3,y3,z3} {x4,y4,z4} ... {xn, yn, zn}

Coordinates:

{-2,-1,0} {1,-2,0} {2,0,0} {0,2,0} {-2,1,0}
{0,-0.3,-1} {0,.5,-.7} {0,.7,1} {0,-.7,1} {0,-1,0}

Polygons

An example DFN for this input is found in dfnWorks-main/examples/user_polygons.

userPolygonByCoord

Description: Selection if user defined polygons are going to be used. If this option is activated, then the file :refPolygonByCoord_Input_File_Path is read. The path to that file must be valid.

Type: boolean (0/1)

0: Do not include user defined polygons

1: Do include user defined polygons

Note

Each polygon can have a different number of vertices.

dfnGen automatically outputs the file polygons.dat which can be read back in using this option to create the same DFN.

PolygonByCoord_Input_File_Path:

Description: File path for user defined polygons

Type: string

Example:

DFN.params['UserEll_Input_File_Path']['value'] = '/dfnWorks/examples/user_polygons/polygons.dat'

Polygon file format

The first line is a keyword nPolygons, the number of fractures in the file. Then each line after nPolygons is a different fracture. The first entry is an integer with the number of vertices in that fracture. The remaining entries are the vertex coordinates. The coordinate format is {x1,y1,z1} {x2,y2,z2} {x3,y3,z3} {x4,y4,z4} … {xn, yn, zn}

General Example:

nPolygons: 1
4 {x1,y1,z1} {x2,y2,z2} {x3,y3,z3} {x4,y4,z4} // fracture 1 has 4 vertices with these coordinates

Example generated by dfnGen:

nPolygons: 13
{0.614809755508, -5, 10} {0.215302589745, -5, 5.14052566974} {0.545132019741, -3.76296408041, 5.01135305297} {1.46205561432, -1.11169723114, 7.28911258873} {1.7422671348, -0.903335314403, 10}
{-5, 5, -7.34275683413} {-5, -3.19676496723, -8.52840001844} {-2.54841054822, -3.3215018603, -8.70265907788} {2.28455866847, 0.968743065242, -8.39004354883} {2.5300049043, 5, -7.82257143457}
{0.169537908304, -1.10365780918, 7.89449659536} {3.39229757501, -1.47097810869, 9.7368040684} {5, -0.396173810104, 9.9199696155} {5, 5, 6.76351044547} {0.192549006049, 5, 4.33581920939} {-0.157462422292, 4.76600532497, 4.29594241204} {-1.30082072643, 1.47978607543, 5.64081751301}
{-0.793278268371, 5, 1.81778296407} {-0.561983329033, 3.45819042638, 3.44636375172} {1.4541413343, -3.51825209439, 3.66719739398} {2.0912558548, -5, 2.1739128129} {3.74246641127, -5, -10} {0.809628560699, 5, -10}
{-3.56729801834, -4.10664963232, -7.17895163585} {-2.75834169562, -5, -7.23742727251} {2.80010131269, -5, -7.26666449977} {3.40228077595, -4.45665913893, -7.23685468994} {3.54844410108, -1.5749811435, -7.06272440502} {1.61045433532, 0.565188057474, -6.92263630123} {-1.27643915621, 0.710166484812, -6.89865208954} {-3.42113429321, -1.22497133918, -7.00482133497}
{1.61970921408, 0.322281059007, 8.27249031626} {1.91468659533, -0.549550927249, 10} {2.19700291895, -5, 10} {1.3154355331, -5, 3.64584005023} {1.20544838483, -3.98437001886, 3.31745142962} {1.22589362057, -0.804792681255, 4.91861492809}
{-4.70593999999, -3.29639431251, -7.25224389054} {-3.10094407568, -4.6562865987, -7.03245087974} {-0.992518232701, -4.50612429324, -7.10741842947} {0.384249987443, -2.93387033715, -7.43323157864} {0.222868762162, -0.860529584164, -7.81903344627} {-1.38212753352, 0.499362646346, -8.03882643837} {-3.4905528176, 0.349200223043, -7.9638588789} {-4.8673209588, -1.22305329999, -7.63804581282}
{5, 5, -3.39564264412} {2.56312416852, 5, -4.08462835745} {2.41898893677, 4.65124788861, -4.11909954775} {3.10520773081, 2.8645938936, -3.89290711889} {4.80872562941, 2.11160312936, -3.39770554375} {5, 2.19173173493, -3.34506895229}
{-5, 2.42895858094, 6.20485792137} {-5, -5, 4.85177752427} {-1.81351205493, -5, 4.99702019362} {0.0853427250495, -2.66597219167, 5.50868187563} {-0.289753327606, 0.588931258258, 6.08441961571} {-2.88990150472, 2.64805531643, 6.34094328974}
{-0.922507014307, -1.71519798881, 2.85778630995} {-0.841071899053, 0.310044679731, 1.25820816606} {-1.26426496474, 2.84566856205, 1.49988903618} {-1.94418542615, 4.40633923745, 3.44125563949} {-2.48254521057, 4.07783735953, 5.94508200102} {-2.5639802392, 2.05259419185, 7.54466008318} {-2.14078724661, -0.483028953749, 7.30297907019} {-1.4608669326, -2.04369954706, 5.36161304612}
{2.18143095055, -0.610312831185, -4.21771261931} {2.80909183961, 0.814183043594, -4.47247873318} {2.26469088948, 2.29432736239, -4.44327042469} {0.867130728085, 2.96307141873, -4.14719749191} {-0.564917036364, 2.42867426252, -3.75769541671} {-1.19257780773, 1.00417817281, -3.50292931657} {-0.648176891617, -0.475965761662, -3.53213764385} {0.74938298608, -1.14470985076, -3.82821050463}
{-1.27165416308, 5, 10} {-1.97370232204, 1.13046740212, 10} {-2.01807341608, 0.962283071202, 9.35725325459} {-1.83562647916, 2.23286105726, 7.12746635144} {-1.40616097581, 4.67958113114, 6.45759785589} {-1.34398137987, 5, 6.64526675756}

nPolygons

Description: Number of polgyons/fractures

Type: integer

Example:

nPolygons: 3 // Read in three polygons/fractures