tcngf-pf.1 - cngf-pf - continuum model for granular flows with pore-pressure dynamics (renamed from 1d_fd_simple_shear)
(HTM) git clone git://src.adamsgaard.dk/cngf-pf
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tcngf-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