State is unclear in the `star` pointer.
- Dominant language
- Fortran
- Stars
- 249
- Forks
- 82
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 3
Description
## Intro
I've been trying to understand what makes `state` so tricky in MESA/`star`. This is my attempt at expressing what's wrong, and what we might do about it.
Everything here has some caveats, the biggest of which is a 'so far as I know' that should be attached to every statement about MESA.
## Current State
There are at least six different kinds of state that live in `star_data`:
1. Metadata. Flags and configuration, mostly defined in `star_data_step_input.inc`.
2. The 'ground truth' structure variables. E.g. `xh` (structure), `xa` (composition), `mlt_vc` (for TDC).
3. Starting values. Used for evaluating time derivatives.
4. Copies of structure variables. e.g. `s%lnR` is a copy of `s%xh(i_lnR)`. Presumably this is for convenience and code clarity. Note that these are copies and not pointers.
5. Intermediate results. For instance results of `eos` calls or intermediate calculations like `csound` and `z53bar`.
6. Outputs that go in history or profiles or pgstar windows or which are used for debugging.
There are also at least three different problems we routinely hit with state:
1. Sometimes an output becomes an intermediate result when a piece of code is written that relies on it. These may need updating at different points in time, resulting in inconsistencies like #66.
2. Different kinds of state need to be updated at different times when `star` performs iterations, starts a step, finishes a step, retries, model writing/reading, etc. This was a major source of bugs in the development of TDC, and even determining when a particular piece of state gets updated is challenging/time-consuming.
3. It is not clear which intermediate results depend on which other intermediate results, and what those dependencies look like. This makes it easy for things to get out of sync. This came up in developing `eps_mdot`, where at one point `s%R` and `s%lnR` got out of sync.
## Proposed Solution
I am not sure of the best solution here, but the best I've come up with is to the data inside `star_data` into six sub-types:
1. `meta`
2. `struct`
3. `start`
4. `ease`
5. `inter`
6. `output`
These correspond to the different kinds of state above.
A few examples:
- `s%v_flag` becomes `s%meta%v_flag`
- `s%xa` becomes `s%struct%xa`
- `s%lnR` becomes `s%ease%lnR`
- `s%mlt_vc_old` becomes `s%start%mlt_vc`
- `s%eps_mdot` becomes `s%inter%eps_mdot`
- `s%center_ye` becomes `s%output%center_ye`
These sub-types help organize the logic, at the cost of being more verbose. But for instance you could pass them directly to subroutines, so a routine that calculates outputs could be passes `s%output` -> `o` and then you write to `o%center_ye`.
We can also attach rules to some of the sub-types:
1. `meta` only gets touched by `run_star_extras` and initialization routines. Flags don't get changed by the rest of `star`.
2. `struct` only gets modified by the solver. In some cases this just means copying an intermediate variable (e.g. there can be an `mlt_vc` variable that lives in `inter`, but the 'ground truth' will always be the version the solver writes into `struct`). This ensures that you **know for sure** that `struct` data was last updated at the end of the most recent iteration.
3. `start` variables only get set at the start of a step or by initialization routines (including model reading).
4. `ease` variables would be written once per iteration, always at the end of a solver call. This ensures that they remain just convenient places to put copies of structure variables and/or one-off derived quantities like `eos` outputs.
5. `inter` variables would be a sort of catch-all for state we can't easily put in the other buckets. The goal should be for this to be a small category.
6. `output` variables would be written once per step. They would never be read except by the profile/history/pgstar/model writing routines. We could enforce this with a derived type, or else check for it with a linter.
I think this would make the state much more manageable, and make it a lot clearer what gets modified where.
I'd be very interested to hear what others think though!
Contributor guide
Research direction
Start by reading star_data_step_input.inc and tracing the six state categories described in the issue through star_data. The proposed sub-types and update rules have no agreed implementation or acceptance criterion; the issue is not done until maintainers choose and specify a concrete state-organization plan.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- fortran
- Domain
- hpc
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100