measure create command

Syntax

measure create keyword ...

Primary keywords:

bins id position radius tolerance position-x position-y position-z

Create a measurement region. Measurement regions are {disks in 2D; spheres in 3D}. The measurement calculation is triggered whenever a clean command is invoked, or whenever a FISH intrinsic that queries a measured value is invoked (see “Measure Intrinsics”).

bins i fl fh: Specify the number of bins (i) and the lowest and highest (fl and fh) bin edges for the size distribution calculation. All bodies (e.g., clumps and balls) that fall within the measurement region are binned based on the {area in 2D; volume in 3D} equivalent {circle in 2D; sphere in 3D} diameters. The cumulative volume percentage (between 0 and 1) of bodies is calculated and can be exported to a table with the measure dump command. Table entries hold the average values of each pair of bin boundaries and the corresponding computed percentages.

id i: Measurement ID. If not specified, the next available ID is assigned.

position v: Position of the center of the measurement object. Default to the origin of the global axis system.

radius f: Radius of the measurement object. Default is 1.0

tolerance f

Specify the relative tolerance for accumulating the volume of bodies that intersect the measurement region in the porosity calculation. The volumes of bodies that fall completely within the measurement region are summed as \(V_s\); \(V_{\cap}\) holds the sum of body volumes that intersect the measurement region and a list, intersectList, of these bodies is created. The bodies in intersectList are revisited in order of greatest volume. When visiting a body in intersectList, the volume of the body is removed from \(V_{\cap}\) and the volume of intersection is added to \(V_s\). When \(V_{\cap} / (V - V_s) \leq f\), then no more intersecting bodies are visited. This guarantees that the actual porosity will be within a relative tolerance of f from the calculated value. For f, not 0, the porosity will generally be slightly overestimated. By default, f = 0.01.

For clumps, a voxelization approach is used to calculate the volume of intersection. The {square in 2D; cubical in 3D} axis-aligned bounding box enclosing all pebbles is recursively bisected into boxes five times. At each level, each box is tested for inclusion in both the clump and the measurement region. Retained for further refinement are boxes that are inside the measurement region and intersect the clump surface, those that are inside the clump and intersect the measurement region surface, and those that intersect both the measurement region surface and clump surface. The volumes of the boxes that fall completely within the clump and measurement region are added to the intersection sum. A correction is applied based on the convergence of the volume with each level of refinement (using a relationship for the logarithm of the length of a side of a box at the current refinement level and the accumulated volume to that level) to estimate the intersection volume in an efficient and accurate way. Thus low percentage values will not translate into more accurate estimations of the volume of intersection, as such calculations can be very time consuming.

position-x f: \(x\)-coordinate of the center of the measurement object. Default is 0.0

position-y f: \(y\)-coordinate of the center of the measurement object. Default is 0.0

position-z f (3D ONLY): \(z\)-coordinate of the center of the measurement object. Default is 0.0

Usage Example

The following example illustrates how the measure create command can be used to operate on measurement regions.

To create a measurement region to measure the porosity, the coordination number, the stress, and strain:

measure create radius 4.0 tolerance 0.001

To create a measurement region to plot a particle size distribution curve:

measure create id 1 bins 100 0.0 0.5 radius 4.0