PyREC scaffolding (from YREC development, 7be4133)

What it is. YREC, the Yale Rotating Evolution Code, at its development branch's commit 7be4133 (Nov 2, 2026; the map was written for 09c3b9b and moved on Oct 31 and Nov 9): 282 fixed-form Fortran files in src/, about one routine per file. 85 of them are modules (*_mod.f), which replaced the COMMON blocks of the release rp_1 (where this site began): routines share data through the modules they USE (see the Modules page; every module variable is in the Glossary, under its name in lower case) as much as through arguments, so a routine's modules matter as much as its calls. Since rp_1, the development branch has also removed legacy options (the MHD equation of state, the OPAL 1995 and 2001 equations of state, the Kurucz 1990, LAOL89 (all but its pure-metal table), Alexander 1995 and OPAL92 opacities, and the Monte Carlo loop), with 58 files, and fixed a number of bugs; each page's explanation ends with a "Changed since rp_1" line.

Where to start. main.f is the main program (it has no PROGRAM statement), and its page walks through the whole run. In order, it:

1. reads the run's settings and tables: PARMIN, then SETUPS;
2. optionally sets up a calibration: of the Sun (SETCAL) or of a star of given $L$ and $T_\mathrm{eff}$ (SETSCAL);
3. for each "kind card" (one run of the job), reads the starting model (STARIN), writes the headers (WRTHEAD) and sets the first time step (HTIMER);
4. evolves it model by model. Each step: mass loss (MASSLOSS); mixing, burning and settling (MIX, with KEMCOM and GRSETT); rezoning (HPOINT); the structure, by four levels of the Henyey iteration (CRRECT), where a divergence ends the run (despite a comment about cutting the step, see main.f); convective mixing (MIXCZ); rotation (GETW, FPFT); lithium burning (LIRATE88, LIBURN); the next time step (HTIMER); output (WRTOUT); and the stop conditions. The composition is not among the Henyey unknowns: MIX changes it over the step with the current structure, the Henyey iteration then solves for $P$, $T$, $r$, $L$ with the composition fixed, and levels 3 and 4 redo the burning and mixing, from the start-of-step composition, with the new structure (an operator split; CRRECT, step 2);
5. ends each kind card with PUTSTORE and the calibration checks (CHKCAL, CHKSCAL).

How a run goes. (From YREC's documentation, yrec.readthedocs.io, as the code does it.) One call, yrec control.nml1 physics.nml2, runs one job on one star. PARMIN reads the two namelists: the control namelist names the starting model, the tables and the output files (paths may use {YREC_INPUT}, {YREC_START}, {YREC_OUTPUT}, filled from environment variables) and lists the job's runs, the "kind cards"; the physics namelist chooses the physics (equation of state, opacities, atmosphere, nuclear rates, convection and overshoot, diffusion, rotation) and the numerical controls. SETUPS reads the tables. Since YREC is a relaxation code, every job starts from a converged model, from the library in input/models/ (most often one at the deuterium-burning birthline) or from an earlier job's .last file, read by STARIN.

Each kind card then rescales the model to the wanted mass, composition and mixing length (RSCALE; with a zero time step, or with evolution for a pre-main-sequence model, which has no static solution unless deuterium burning carries its luminosity, see main.f, step 3 of the evolution step), or evolves it, model by model, until a number of models, an age or a central abundance is reached.

After each model, WRTOUT appends a line to the .track file (the global properties over time) and numerical details to .short, rewrites .last (the latest model, to restart from), and, as asked, writes snapshots of the structure to .store (PUTSTORE) and pulsation files (WRTMOD). A grid of stars is many such jobs, run by scripts or by the Python wrapper (pip install yrec), which runs the same executable. The test suite (testsuite/, run with pytest) runs a set of such jobs, solar models, brown dwarfs and stars of 0.1 to 9 $M_\odot$ evolved to various stages, and compares their outputs with stored reference outputs; it is how a change to the code is checked.

The code's conventions. Changes in the source carry a comment with their date and the author's initials ("MHP 10/24," "G. Somers 11/14," "KC 2025-05-31," and, for changes made with an AI assistant, "MHP via Claude"), which is why the pages list them. Variable names still follow the old implicit types (A–H and O–Z real, I–N integer, L logical), although every file now declares its types under IMPLICIT NONE. Character strings stay out of the modules, as they once stayed out of the COMMON blocks: file names are read and tied to unit numbers in PARMIN, and the few strings used elsewhere (the version, the mixture's name) are passed as arguments through the main program. The namelist variables live in two modules, NMLPAR_MOD and NMLBYPASS_MOD, with their defaults. A physics routine returns its derivatives with its value (an opacity with its derivatives in density and temperature, for example), so an alternative must return the same set.

Each file's page has an outline in the margin, its text on the left, and the whole file's code on the right, which stays in view: the Fortran, re-indented by its loops and IF blocks (switch to "as in YREC" for the code as written), or its Python translation, whose blocks name the Fortran lines they translate. Every link to lines (in a question, a bug, a call) shows those lines in the code, and a ↗ beside it opens them on GitHub. Each routine's section gives the modules it uses (each linked to the module's page, which lists every unit using it), what calls it, and a flowchart of its calls in the order of the source, nested in boxes for its loops and branches; lines with a compiler's warning (gfortran) or a linter's finding (ruff, in the Python) are marked. Calls are found by reading the code, not by running it. Only src/ is mapped; the .f files under input/, tools for the data tables, are left out. Many files carry changes marked "KC 20…" (Kaili Cao's), with the old lines kept as comments beside them, which is where they are read.

A route through the 15 topics of Files by topic, for a newcomer who wants to read every page. Within each topic, read the files named here first, then the rest in the order their topic's table lists them (the routines, then the modules, which are short and best read beside the routines that use them).

1. The main program and the run's control: main.f first, its page walks through a whole run; then rscale.f, and the calibrations setcal.f and chkcal.f.
2. Input: parmin.f with nmlpar_mod.f (what every setting means), then setups.f and starin.f.
3. The structure equations and the Henyey solver: crrect.f, coefft.f (the four equations), then reduce.f and hsolve.f.
4. Atmospheres, the envelope and the boundary conditions: surfbc.f (the envelope triangle), envint.f, then qenv.f and qatm.f.
5. The equation of state: eqstat.f, eqstat2.f (the choice and blending of the tables), then eqsaha.f.
6. Opacities: getopac.f, then setupopac.f and getopal95.f.
7. Nuclear reactions, energy generation and neutrinos: engeb.f, rates.f, kemcom.f.
8. Convection, overshoot and the mixing of composition: mix.f (the composition over a step), convec.f, tpgrad.f (mixing-length theory), oversh.f, mixcz.f.
9. The time step and rezoning: htimer.f, hpoint.f.
10. Output: wrtout.f, wrthead.f, putstore.f.

This completes a run without rotation or diffusion. The remaining topics are options, each switched on by the namelists:

1. Microscopic diffusion and settling: grsett.f (the older treatment), then microdiff.f (the newer one) and thdiff.f (Burgers' equations).
2. Rotation, the structure of a rotating star: fpft.f, shape.f, momi.f, getrot.f.
3. Rotation, angular-momentum transport and rotational mixing: getw.f (the driver), midmod.f, seculr.f, vcirc.f, codiff.f.
4. Angular-momentum loss and mass loss: mwind.f, gettau.f (the overturn time), massloss.f, mdot.f.
5. Numerical utilities: as the other pages call them; intrp2.f, interp.f and osplin.f are the most used.

Each page has questions for the experts, placed where their context is, and, where the code seems wrong, suspected bugs, each with a possible fix in the code's own style, each checked by running YREC (Nov 9-10, 2026: what reaches it, whether its faulty condition occurred, and what its fix changed), and each marked by what the runs showed; each topic of Files by topic lists its suspected bugs and questions in tables of their own (being reorganized this way page by page, from Nov 9, 2026; the opacity pages are done). The development branch has already fixed several found at rp_1 (for example, MASSLOSS called MDOT with one argument too many, and SECULR's whole-domain option was never switched on). Some that remain: GRSETT's convergence test ignores negative changes, and its coefficient correction sits one midpoint off; in SNEUT, cap-cap stands where cap*cap is expected; VCIRC's restored μ-current option divides by the speed of light CC, which is never set; and the acoustic-depth output (CALCAD) never runs, since nothing sets its switch LACOUT (see ACDPTH_MOD).

Found in passing. Four CALLs name routines not in src/: DERIV (in MMID, a routine passed as an argument, QENV or QATM) and, in PARMIN, GETARG, GETENV and SYSTEM (compiler extensions for the command line, the environment and the shell).

An overhaul goes in four stages: a documentation site for the old code (this part of the site); the documentation of a new code on the same site, with references to the old one; the new code, with benchmarks (same inputs, same outputs); and a paper. The first stage is complete for rp_1, where every file had an explanation with questions for the code's experts and every page went through one round of review and revision; a page's review findings, folded at its end, refer to rp_1. On Oct 27 every page was moved to 09c3b9b, each with its Python translation in the current structure (the pyrec repository): the translation is checked only by compiling it, and is to be tested routine by routine against the Fortran. On Oct 31 the pages moved to a8a5950, with YREC's public documentation, the YREC paper's notation, the files grouped by topic with a reading path, and the glossary. On Nov 9 they moved to 7be4133, after a round of bug fixes by YREC's developers; each page changed since ends with a "Changed since a8a5950" line. The second stage is drafted: a new design, a high-level design on one page (Nov 9, 2026): a Model holding the star's state and its history, with its physics and numerical methods as families of callables, each a Python base class, in Python with Numba.

The pages write the physics in the symbols of the YREC paper (Pinsonneault et al., "The YREC Stellar Evolution Code: Public Data Release," YREC_Public_Data_Release_Paper_revised.pdf in the repository's root), and the code's variables in code font. The paper names some quantities only in words; for those, marked *, the pages use the usual symbol. Many arrays hold logarithms (base 10) of the quantity, per shell. The code works in cgs, except that HL is in $L_\odot$ and is not a logarithm, SMASS is in $M_\odot$, the age DAGE is in Gyr and the step DDAGE in yr (DELTS, the same step, in s).

The 282 files, in 15 topics, in the order of the reading path (in Reading this site); within each topic the routines come first, in reading order, then the modules that hold its data.