cngf-pf.1 (8241B)
1 .Dd $Mdocdate$ 2 .Dt CNGF-PF 1 3 .Os 4 .Sh NAME 5 .Nm cngf-pf 6 .Nd simulate granular flows with pore-pressure dynamics 7 .\" .Sh LIBRARY 8 .\" For sections 2, 3, and 9 only. 9 .\" Not used in OpenBSD. 10 .Sh SYNOPSIS 11 .Nm 12 .Op Fl A Ar grain-nonlocal-ampl 13 .Op Fl a Ar fluid-pressure-ampl 14 .Op Fl b Ar grain-rate-dependence 15 .Op Fl C Ar fluid-compressibility 16 .Op Fl c Ar grain-cohesion 17 .Op Fl D Ar fluid-diffusivity 18 .Op Fl d Ar grain-size 19 .Op Fl e Ar end-time 20 .Op Fl F 21 .Op Fl f Ar applied-shear-friction 22 .Op Fl g Ar gravity-accel 23 .Op Fl H Ar fluid-pressure-phase 24 .Op Fl h 25 .Op Fl I Ar file-interval 26 .Op Fl i Ar fluid-viscosity 27 .Op Fl j Ar time-step 28 .Op Fl K Ar dilatancy-constant 29 .Op Fl k Ar fluid-permeability 30 .Op Fl L Ar length 31 .Op Fl l Ar applied-shear-vel-limit 32 .Op Fl m Ar grain-friction 33 .Op Fl N 34 .Op Fl n Ar normal-stress 35 .Op Fl O Ar fluid-pressure-top 36 .Op Fl o Ar origo 37 .Op Fl P Ar grain-compressibility 38 .Op Fl p Ar grain-porosity 39 .Op Fl q Ar fluid-pressure-freq 40 .Op Fl R Ar fluid-density 41 .Op Fl r Ar grain-density 42 .Op Fl S Ar fluid-pressure-pulse-shape 43 .Op Fl s Ar applied-shear-vel 44 .Op Fl T 45 .Op Fl t Ar curr-time 46 .Op Fl U Ar resolution 47 .Op Fl u Ar fluid-pulse-time 48 .Op Fl V Ar bot-vel 49 .Op Fl v 50 .Op Fl Y Ar max-porosity 51 .Op Fl y Ar min-porosity 52 .Op Fl X Ar relative-tolerance 53 .Op Fl x Ar max-iter 54 .Op name 55 .Sh DESCRIPTION 56 The 57 .Nm 58 utility simulates the coupled continuum dynamics of granular 59 deformation and pore pressure. 60 The simulation space is one-dimensional and undergoes confined, 61 simple shear at a pretedermined velocity or friction ratio. 62 The effective stress is modulated by pore-pressure dynamics when 63 fluid dynamics are enabled. 64 .Pp 65 The arguments are as follows: 66 .Bl -tag -width Ds 67 .It Fl A Ar grain-nonlocal-ampl 68 Amplitude of granular non-locality [-] (default 0.4). 69 .It Fl a Ar fluid-pressure-ampl 70 Amplitude of fluid-pressure perturbations [Pa] (default 0). 71 Only relevant with fluid dynamics enabled 72 .Fl ( F ) . 73 .It Fl b Ar grain-rate-dependence 74 Granular rate dependence beyond yield [-], (default 0.9377). 75 .It Fl C Ar fluid-compressibility 76 Fluid adiabatic compressibility [Pa^-1] (default 3.9e-10). 77 Only relevant with fluid dynamics enabled 78 .Fl ( F ) . 79 .It Fl c Ar grain-cohesion 80 Granular material cohesion [Pa] (default 0). 81 .It Fl D Ar fluid-diffusivity 82 Fluid diffusion coefficient [m^2/s] (default -1). Overrides fluid 83 permeability (-k), grain compressibility (-P), fluid compressibility 84 (-C), and fluid viscosity (-i). Do not use for transient simulations 85 (-T). Disabled when set to a negative value. 86 .It Fl d Ar grain-size 87 Granular material representative grain size [m] (default 0.04). 88 .It Fl e Ar end-time 89 Simulation end time [s] (default 1). 90 .It Fl F 91 Enable pore-space fluid dynamics. 92 .It Fl f Ar applied-shear-friction 93 Applied ratio between shear stress and normal stress at the top 94 boundary [-] (default 0.45), overridden by 95 .Fl s 96 and 97 .Fl l 98 if these are set. 99 .It Fl g Ar gravity-accel 100 Gravity magnitude [m/s^2] (default 9.81). 101 .It Fl H Ar fluid-pressure-phase 102 Phase of fluid-pressure perturbations [s] (default 0). 103 Only relevant with fluid dynamics enabled 104 .Fl ( F ) . 105 .It Fl h 106 Show usage information. 107 .It Fl I Ar file-interval 108 Simulation time interval between writing output to disk [s] (default 109 1.0). 110 .It Fl i Ar fluid-viscosity 111 Fluid dynamic viscosity [Pa*s] (1.787e-3). 112 Only relevant with fluid dynamics enabled 113 .Fl ( F ) . 114 .It Fl j Ar time-step 115 Override numerical time step length [s]. 116 Only relevant with fluid dynamics enabled 117 .Fl ( F ) . 118 Outside of stability testing, is not recommended to specify the 119 time step length manually. 120 .It Fl K Ar dilatancy-constant 121 Factor relating dilatancy angle to the volume fraction [-] (default 122 4.09). Only relevant with transient granular dynamics enabled 123 .Fl ( T ) . 124 .It Fl k Ar fluid-permeability 125 Darcian intrinsic permeability of granular material [m^2] (default 126 1.9e-15). 127 Only relevant with fluid dynamics enabled 128 .Fl ( F ) , 129 and without transient dynamics. 130 In transient simulations 131 .Fl ( T ) 132 the permeability value is overridden by the Kozeny-Carman relationship 133 (k = d^2/180 * phi^3 * (1 - phi)). 134 .It Fl L Ar length 135 Simulation domain length [m] (default 1). 136 .It Fl l Ar applied-shear-vel-limit 137 Upper limit to modeled shear velocity [m/s] (default nan), overrides 138 .Fl f 139 and 140 .Fl s . 141 .It Fl m Ar grain-friction 142 Grain friction coefficient [-] (default 0.404026). 143 .It Fl N 144 Normalize output velocities to the range [0;1]. 145 .It Fl n Ar normal-stress 146 Normal stress applied at the top boundary [Pa] (default 120e3). 147 .It Fl O Ar fluid-pressure-top 148 Fluid pressure applied at the top boundary [Pa] (default 0). 149 Only relevant with fluid dynamics enabled 150 .Fl ( F ) . 151 .It Fl o Ar origo 152 Simulation domain origo [m] (default 0). 153 .It Fl P Ar grain-compressibility 154 Granular material compressibility [Pa^-1] (default 1e-8). 155 .It Fl p Ar grain-porosity 156 Granular material porosity [-] (default 0.25). 157 .It Fl q Ar fluid-pressure-freq 158 Frequency of fluid-pressure perturbations [s^-1] (default 1). 159 Only relevant with fluid dynamics enabled 160 .Fl ( F ) . 161 .It Fl R Ar fluid-density 162 Fluid density [kg/m^3] (default 1000). 163 Only relevant with fluid dynamics enabled 164 .Fl ( F ) . 165 .It Fl r Ar grain-density 166 Granular material density [kg/m^3] (default 2600). 167 .It Fl S Ar fluid-pressure-pulse-shape 168 Shape of pulse perturbations in fluid pressure at the top boundary. 169 Valid options are 170 .Ar triangular 171 (default) or 172 .Ar square . 173 Only relevant with fluid dynamics enabled 174 .Fl ( F ) . 175 .It Fl s Ar applied-shear-vel 176 Shear the material under constant velocity [m/s] instead of a friction value. 177 Overrides 178 .Fl f 179 and is overridden by 180 .Fl l . 181 .It Fl T 182 Enable transient granular properties. 183 .It Fl t Ar curr-time 184 Simulation start time [s] (default 0). 185 .It Fl U Ar resolution 186 Numerical resolution of simulation domain [-] (default nan). If 187 not set, the cell size equals the grain size. 188 .It Fl u Ar fluid-pulse-time 189 Time of fluid-pressure pulse peak [s] (default nan). 190 Only relevant with fluid dynamics enabled 191 .Fl ( F ) . 192 .It Fl V Ar bot-vel 193 shear velocity at base [m/s] (default 0). 194 .It Fl v 195 Show version information. 196 .It Fl Y Ar max-porosity 197 Granular material porosity [-] at inertia number I=1 in transient 198 simulations 199 .Fl ( T ) 200 (default 0.55). 201 .It Fl y Ar min-porosity 202 Minimum granular material porosity [-] in transient simulations 203 .Fl ( T ) 204 (default 0.20). 205 .sp 206 .It Fl X Ar relative-tolerance 207 Sets the relative tolerance criteria for the granular solver (default 208 1e-5). 209 .It Fl x Ar max-iter 210 Set the maximum number of iterations in the granular solver (default 211 100000). 212 Simulations with many cells require higher values. 213 .El 214 The final simulation state is written to stdout, see 215 .Sx OUTPUT FORMAT 216 for a description of the data format. 217 .Sh OUTPUT FORMAT 218 The output consists of the following tab-delimited fields, with one 219 row per cell in the simulation domain: 220 .Pp 221 .Bl -enum -width Ss -compact 222 .It 223 position [m] 224 .It 225 shear velocity [m/s] 226 .It 227 effective normal stress [Pa] 228 .It 229 fluid pressure [Pa] 230 .It 231 friction [-] 232 .It 233 shear strain rate [-] 234 .It 235 porosity [-] 236 .It 237 inertia number [-] 238 .It 239 shear stress [Pa] 240 .It 241 cumulative shear displacement [m] 242 .El 243 .Sh FILES 244 If 245 .Ar name 246 is set, the simulation state is written to files in the current 247 directory named in the format 248 .Pa <name>.outputDDDDD.txt . 249 Here, DDDDD is a integer counter starting from 00000, and incrementing 250 by 1 for each new file. 251 Each file contains the state at a single point in simulation time. 252 The output format is specified in the section 253 .Sx OUTPUT FORMAT , 254 and output files are generated with the interval specified with 255 .Fl I Ar file-interval . 256 .Sh EXIT STATUS 257 .Nm 258 exits 0 on success, and >0 if a runtime error occurs: 259 .Pp 260 .Bl -tag -width Ds -compact 261 .It 0 262 successful exit 263 .It 1 264 unspecified error 265 .It 2 266 .Xr pledge 2 267 error 268 .It 10 269 transient solver error 270 .It 11 271 fluid solver error 272 .It 12 273 granular solver error 274 .It 20 275 time step error 276 .El 277 .Sh EXAMPLES 278 Plot critical-state shear velocity as a function of depth: 279 .Pp 280 .Dl $ cngf-pf | gnuplot -e 'set term pdf; p \&"-\&" u 2:1 w lp' > out.pdf 281 .\" .Sh DIAGNOSTICS 282 .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. 283 .\" .Sh ERRORS 284 .\" For sections 2, 3, 4, and 9 errno settings only. 285 .Sh SEE ALSO 286 .Xr gnuplot 1 , 287 .Xr max_depth_simple_shear 1 , 288 .Xr shear_flux 1 289 .Sh AUTHORS 290 .An Anders Damsgaard Aq Mt anders@adamsgaard.dk