0
# Gas Physics Functions
1

2
Standard functions for gas disk physics including thermodynamics, viscosity, pressure profiles, and hydrodynamic evolution. These functions implement the gas disk physics with performance-critical calculations accelerated by Fortran extensions.
3

4
## Capabilities
5

6
### Thermodynamic Properties
7

8
Functions for calculating gas temperature, pressure, and sound speed.
9

10
```python { .api }
11
from dustpy.std import gas
12

13
def gas.cs_isothermal(sim):
14
    """
15
    Calculate isothermal sound speed.
16

17
    Parameters:
18
    - sim: Simulation object
19

20
    Returns:
21
    numpy.ndarray: Isothermal sound speed [cm/s]
22
    """
23

24
def gas.P_midplane(sim):
25
    """
26
    Calculate midplane gas pressure.
27

28
    Parameters:
29
    - sim: Simulation object
30

31
    Returns:
32
    numpy.ndarray: Midplane pressure [g/cm/s²]
33
    """
34

35
def gas.T_passive(sim):
36
    """
37
    Calculate passive irradiation temperature.
38

39
    Computes gas temperature from stellar irradiation
40
    assuming passive heating without viscous dissipation.
41

42
    Parameters:
43
    - sim: Simulation object
44

45
    Returns:
46
    numpy.ndarray: Temperature [K]
47
    """
48

49
def gas.rho_midplane(sim):
50
    """
51
    Calculate midplane gas mass density.
52

53
    Parameters:
54
    - sim: Simulation object
55

56
    Returns:
57
    numpy.ndarray: Midplane mass density [g/cm³]
58
    """
59

60
def gas.n_midplane(sim):
61
    """
62
    Calculate midplane number density.
63

64
    Parameters:
65
    - sim: Simulation object
66

67
    Returns:
68
    numpy.ndarray: Midplane number density [1/cm³]
69
    """
70
```
71

72
### Scale Heights and Geometry
73

74
Functions for calculating characteristic length scales in the gas disk.
75

76
```python { .api }
77
def gas.Hp(sim):
78
    """
79
    Calculate pressure scale height of the gas disk.
80

81
    The pressure scale height determines the vertical
82
    extent of the gas disk and affects dust settling.
83

84
    Parameters:
85
    - sim: Simulation object
86

87
    Returns:
88
    numpy.ndarray: Pressure scale height [cm]
89
    """
90

91
def gas.eta_midplane(sim):
92
    """
93
    Calculate midplane pressure gradient parameter.
94

95
    The eta parameter quantifies the radial pressure gradient
96
    and determines the strength of gas drag on dust particles.
97

98
    Parameters:
99
    - sim: Simulation object
100

101
    Returns:
102
    numpy.ndarray: Pressure gradient parameter
103
    """
104
```
105

106
### Transport Properties
107

108
Functions for calculating viscosity and transport coefficients.
109

110
```python { .api }
111
def gas.nu(sim):
112
    """
113
    Calculate kinematic viscosity of the gas.
114

115
    Uses the alpha-disk model to compute viscosity from
116
    the turbulent alpha parameter and local disk properties.
117

118
    Parameters:
119
    - sim: Simulation object
120

121
    Returns:
122
    numpy.ndarray: Kinematic viscosity [cm²/s]
123
    """
124

125
def gas.mfp_midplane(sim):
126
    """
127
    Calculate mean free path at the midplane.
128

129
    The mean free path determines the gas drag regime
130
    (Epstein vs. Stokes) for dust particles.
131

132
    Parameters:
133
    - sim: Simulation object
134

135
    Returns:
136
    numpy.ndarray: Mean free path [cm]
137
    """
138
```
139

140
### Velocity Components
141

142
Functions for calculating gas velocity components from disk evolution.
143

144
```python { .api }
145
def gas.vrad(sim):
146
    """
147
    Calculate radial gas velocity from viscous evolution.
148

149
    Includes contributions from viscous spreading and
150
    any external torques or mass sources.
151

152
    Parameters:
153
    - sim: Simulation object
154

155
    Returns:
156
    numpy.ndarray: Radial velocity [cm/s]
157
    """
158

159
def gas.vvisc(sim):
160
    """
161
    Calculate viscous radial velocity component.
162

163
    The radial velocity driven purely by viscous torques
164
    in the standard alpha-disk model.
165

166
    Parameters:
167
    - sim: Simulation object
168

169
    Returns:
170
    numpy.ndarray: Viscous radial velocity [cm/s]
171
    """
172

173
def gas.vtorque(sim):
174
    """
175
    Calculate velocity contribution from external torques.
176

177
    Additional radial velocity from gravitational torques
178
    due to planets or other perturbing bodies.
179

180
    Parameters:
181
    - sim: Simulation object
182

183
    Returns:
184
    numpy.ndarray: Torque-driven velocity [cm/s]
185
    """
186
```
187

188
### Mass Fluxes and Source Terms
189

190
Functions for calculating mass transport and evolution source terms.
191

192
```python { .api }
193
def gas.Fi(sim):
194
    """
195
    Calculate mass flux through radial interfaces.
196

197
    The mass flux determines how gas surface density
198
    evolves due to radial transport processes.
199

200
    Parameters:
201
    - sim: Simulation object
202

203
    Returns:
204
    numpy.ndarray: Mass flux through interfaces [g/cm/s]
205
    """
206

207
def gas.S_hyd(sim):
208
    """
209
    Calculate hydrodynamic source terms.
210

211
    Source terms from viscous evolution, including
212
    effects of radial transport and viscous heating.
213

214
    Parameters:
215
    - sim: Simulation object
216

217
    Returns:
218
    numpy.ndarray: Hydrodynamic source terms [g/cm²/s]
219
    """
220

221
def gas.S_tot(sim):
222
    """
223
    Calculate total source terms for gas evolution.
224

225
    Combines hydrodynamic and external source terms
226
    for the complete gas evolution equation.
227

228
    Parameters:
229
    - sim: Simulation object
230

231
    Returns:
232
    numpy.ndarray: Total source terms [g/cm²/s]
233
    """
234
```
235

236
### Initial Disk Profiles
237

238
Functions for setting up initial gas surface density profiles.
239

240
```python { .api }
241
def lyndenbellpringle1974(r, rc, p, Mdisk):
242
    """
243
    Calculate self-similar disk profile from Lynden-Bell & Pringle (1974).
244

245
    Creates an exponentially tapered power-law surface density
246
    profile commonly used as initial conditions for disk evolution.
247

248
    Parameters:
249
    - r: Radial grid [cm]
250
    - rc: Characteristic radius [cm]
251
    - p: Power-law index
252
    - Mdisk: Total disk mass [g]
253

254
    Returns:
255
    numpy.ndarray: Surface density profile [g/cm²]
256
    """
257
```
258

259
### Integration Functions
260

261
Functions for numerical integration of gas evolution equations.
262

263
```python { .api }
264
def gas.jacobian(sim, x, *args, **kwargs):
265
    """
266
    Calculate Jacobian matrix for gas evolution.
267

268
    Used in implicit integration schemes for stable
269
    evolution of the gas disk equations.
270

271
    Parameters:
272
    - sim: Simulation object
273
    - x: Current state vector
274

275
    Returns:
276
    numpy.ndarray: Jacobian matrix
277
    """
278

279
class gas.impl_1_direct:
280
    """
281
    Direct implicit integration scheme for gas evolution.
282

283
    Provides first-order implicit integration for stable
284
    evolution of viscous disk equations.
285
    """
286
    def __init__(self):
287
        """Initialize implicit integration scheme."""
288
        ...
289
```
290

291
### Utility Functions
292

293
Helper functions for gas simulation setup and maintenance.
294

295
```python { .api }
296
def gas.boundary(sim):
297
    """
298
    Set boundary conditions for gas quantities.
299

300
    Applies inner and outer boundary conditions for
301
    gas surface density and other gas properties.
302

303
    Parameters:
304
    - sim: Simulation object
305
    """
306

307
def gas.enforce_floor_value(sim):
308
    """
309
    Enforce minimum floor values for gas quantities.
310

311
    Prevents numerical issues by ensuring gas properties
312
    remain above physically reasonable minimum values.
313

314
    Parameters:
315
    - sim: Simulation object
316
    """
317

318
def gas.dt(sim):
319
    """
320
    Calculate appropriate time step for gas evolution.
321

322
    Determines stable time step based on viscous time scale
323
    and numerical stability requirements.
324

325
    Parameters:
326
    - sim: Simulation object
327

328
    Returns:
329
    float: Time step [s]
330
    """
331

332
def gas.prepare(sim):
333
    """
334
    Prepare gas integration step.
335

336
    Stores the current value of surface density in a hidden
337
    field for use in integration schemes.
338

339
    Parameters:
340
    - sim: Simulation object
341
    """
342

343
def gas.finalize(sim):
344
    """
345
    Finalize gas integration step.
346

347
    Applies boundary conditions, enforces floor values, and
348
    updates dependent quantities after integration.
349

350
    Parameters:
351
    - sim: Simulation object
352
    """
353

354
def gas.set_implicit_boundaries(sim):
355
    """
356
    Calculate fluxes at boundaries after implicit integration.
357

358
    Sets boundary source terms based on the change in surface
359
    density during the implicit integration step.
360

361
    Parameters:
362
    - sim: Simulation object
363
    """
364
```
365

366
## Usage Examples
367

368
### Basic Gas Properties
369

370
```python
371
from dustpy import Simulation
372
from dustpy.std import gas
373
import dustpy.constants as c
374

375
# Create and initialize simulation
376
sim = Simulation()
377
sim.makegrids()
378
sim.initialize()
379

380
# Calculate basic gas properties
381
sound_speed = gas.cs_isothermal(sim)      # [cm/s]
382
pressure = gas.P_midplane(sim)            # [g/cm/s²]
383
scale_height = gas.Hp(sim)                # [cm]
384
density = gas.rho_midplane(sim)           # [g/cm³]
385

386
# Convert to useful units
387
print(f"Sound speed: {sound_speed/1e5:.1f} km/s")
388
print(f"Scale height: {scale_height/c.au:.2f} AU")
389
```
390

391
### Viscous Evolution Analysis
392

393
```python
394
# Calculate transport properties
395
viscosity = gas.nu(sim)                   # [cm²/s]
396
radial_velocity = gas.vrad(sim)           # [cm/s]
397
viscous_velocity = gas.vvisc(sim)         # [cm/s]
398

399
# Calculate mass flux
400
mass_flux = gas.Fi(sim)                   # [g/cm/s]
401

402
# Time scales
403
viscous_time = sim.grid.r**2 / viscosity  # [s]
404
print(f"Viscous time at 1 AU: {viscous_time[50]/c.year:.1e} years")
405
```
406

407
### Custom Initial Profiles
408

409
```python
410
# Set up Lynden-Bell & Pringle profile
411
r = sim.grid.r                            # [cm]
412
rc = 10 * c.au                           # Characteristic radius
413
p = -1.5                                 # Power-law index
414
Mdisk = 0.01 * c.M_sun                   # Disk mass
415

416
# Calculate initial profile
417
initial_sigma = lyndenbellpringle1974(r, rc, p, Mdisk)
418
sim.gas.Sigma[:] = initial_sigma          # Set as initial condition
419
```
420

421
### Pressure Gradient Effects
422

423
```python
424
# Calculate pressure gradient parameter
425
eta = gas.eta_midplane(sim)
426

427
# This affects dust drift velocities
428
print(f"Pressure gradient parameter at 1 AU: {eta[50]:.3f}")
429

430
# Mean free path affects drag regime
431
mfp = gas.mfp_midplane(sim)               # [cm]
432
particle_size = 0.01                     # 100 micron particles
433
print(f"Knudsen number: {particle_size/mfp[50]:.2e}")
434
```
435

436
### Temperature Profiles
437

438
```python
439
# Calculate passive disk temperature
440
temperature = gas.T_passive(sim)          # [K]
441

442
# Set up temperature-dependent properties
443
sim.gas.T[:] = temperature
444

445
# Recalculate sound speed with new temperature
446
updated_cs = gas.cs_isothermal(sim)       # [cm/s]
447
```