PyREC scaffolding (from YREC development, 7be4133)/ taucal.fGlossary

taucal.f

231 lines · 1 definitions · on GitHub (7be4133)

Python version: taucal.py, 128 lines, on the right (switch to Python above the code).

Variables on this page (6)

cgl, cln, cmsun, json, lrot, taucz

Purpose

TAUCAL computes the convective overturn time scale $\tau_\mathrm{cz}$ (TAUCZ) near the base of the surface convection zone, for a convection zone that lies within the envelope (JVS 02/12). Its comments say the code was taken from MIDMOD, and that the routine is called only from ENVINT.

How it fits

  • Inputs: the envelope's profile, passed by ENVINT as arguments: the shell masses HS2, unlogged masses HS1, convective flags LCZ, $\log r$ (HR), $\log P$ (HP), $\log\rho$ (HD), gravity HG, the convective velocity SVEL, and two temperature gradients DEL1, DEL2 (EDEL1 and EDEL2 in ENVINT, copied from EDELS(1,·) and EDELS(2,·), which STITCH's column list names the radiative and the actual gradient; their difference changes sign at the zone's edge).
  • Who calls it: only ENVINT.
  • Output: TAUCZ in OVRTRN_MOD, shared with GETTAU, ENVINT, MASSLOSS, GETW and others (the wind and mass-loss routines, by their names).
  • Modules: OVRTRN_MOD, NMLPAR_MOD (LROT) and CONSTANTS_MOD.

The method

  1. Going down from the surface, find the first convective shell, then the base of that zone, IMAX; note whether a second, deeper convective zone exists (LTWOCZ, its top ICZTOP); with two zones, IMAX ends at the base of the deeper one. For a single zone ICZTOP is not set (bug 1). The routine also sets HSTOP, HSBOT and LCZSUR, which nothing reads since the test on LCZSUR was commented out (JVS 10/11/13; unused?, lines 106–128↗); the test (HSTOP-HSBOT)/CMSUN .GT. 0 would be true for any zone.
  2. Locate the base $r_b$ where $\nabla_1 - \nabla_2$ changes sign, by linear interpolation between shells IMAX-1 and IMAX (factor $f$), and the pressure scale height there, $$H_p = \frac{P}{\rho\,g},\qquad g = \frac{G m}{r^2}\ \text{(computed here only without rotation)},$$ interpolated with the same $f$.
  3. If the zone is thin, that is, with $r_\mathrm{top}$ the radius of shell ICZTOP, $$\left|1 - \frac{r_b + H_p - r_\mathrm{IMAX}}{r_\mathrm{top} - r_\mathrm{IMAX}}\right| < 0.5,$$ so that the point $r_b + H_p$ lies between the zone's middle and half a width above its top, or there are two zones, the mass-weighted mean velocity over shells IMAX to ICZTOP is used: $$\bar v = \frac{\sum_j \Delta m_j\,\tfrac12 (v_j + v_{j+1})}{\sum_j \Delta m_j},\qquad \tau_\mathrm{cz} = \frac{|r_\mathrm{top} - r_\mathrm{IMAX}|}{\bar v}.$$

  4. Otherwise (the original method), the velocity at one pressure scale height above the base, $v(r_b + H_p)$, by linear interpolation in $\log r$, gives $$\tau_\mathrm{cz} = \frac{H_p}{v(r_b + H_p)} .$$

  5. ENVINT calls TAUCAL only with the old method (LNEWTCZ false; the default is true) and only when the envelope's deepest point is radiative and a point above it convective (JENV > 1, envint.f, lines 937–971↗). So LCZ(1) is false: when a convective point lies below M, the loop leaves the zone and sets IMAX ≥ 2; when only the surface point M is convective (the loop starts at M-1), LCZEX stays false and IMAX = M. IMAX is thus always set in the call, LALLCZ is never set, and the branch TAUCZ = 0 is not reached (settled from the code, Nov 9, 2026: lines 87–101↗, line 122↗, lines 223–224↗).

Design

The routine prints "TauCal" to the screen at every call. A large commented-out block handled fully convective cases.

Suspected bugs, checked by running the code

Each bug is marked by what running the code showed: (changes results, large) or (small), the fix moving a run clearly beyond a null change; (stops the run); (wrong output), the fix changing only what is written; (harmless in the runs), within the noise; (never occurred), the code ran but the fault did not; (not reached); (cannot be reached), a guard prevents it; (withdrawn), the suspicion was wrong.

1. (not reached) ICZTOP is not set for a single zone.

(lines 87–98↗; lines 152–153↗; lines 159–163↗) ICZTOP, the top of the deeper zone, is set only when the loop finds two zones (line 94↗). But the test that chooses the averaging method evaluates HR(ICZTOP) for every zone (lines 152–153↗), and the averaging itself, which the first condition can select for a single zone, sums over shells IMAX to ICZTOP and takes the width from HR(ICZTOP). For a single zone, ICZTOP keeps the value SAVEd from an earlier call with two zones, and is undefined if there was none (an index of 0 would read outside HR). What follows: The choice of method and, if averaging is chosen, TAUCZ depend on an earlier model's zone. Only with the old method (LNEWTCZ false; the default is true), when the envelope holds the zone's base.

A possible fix: take the top of a single zone as ICZTOP:

taucal.f

@@ lines 94–99 @@
                   ICZTOP = I
             ELSE IF( LCZ(I) .AND. .NOT. LCZEX) THEN !First convective point from surface
                   LCZEX = .TRUE.
+C 11/09/26 KC via Claude
+C code changed to set ICZTOP for a single zone too: the thin-zone test
+C and the average below use it.  A second zone overwrites it.
+                  ICZTOP = I
             ENDIF
    71    CONTINUE
          IF(IMAX .LT. 1)THEN

Checked by running YREC (Nov 9, 2026; a line added at each suspected path counted how often it was taken, the outputs otherwise unchanged): Not reached: TAUCAL runs only with LNEWTCZ off (envint.f, line 937↗), and no case of YREC turns it off. The fix was not run. What would reach it: LNEWTCZ = .FALSE., with the base of a single surface convection zone inside the envelope. No comment says a single zone should use an earlier ICZTOP.

Definitions

subroutineTAUCAL

lines 3–231 · GitHub

The convective overturn time near the base of a surface convection zone within the envelope, $H_p/v$ one scale height above the base, or a zone's width over its mean velocity for thin or double zones.

Uses modules CONSTANTS_MOD, DIMENSIONS_MOD, NMLPAR_MOD, OVRTRN_MOD

Called by ENVINT

Change log

The changes since rp_1

Changed since rp_1. Declarations only: COMMON blocks to modules (/OVRTRN/ to OVRTRN_MOD, /ROT/ to NMLPAR_MOD, the constants to CONSTANTS_MOD; the unused /COMP/ and /DEUTER/ dropped), the array size JSON from DIMENSIONS_MOD, IMPLICIT NONE.