Summary

This PR intends to clarify the meaning of "initialization" versus other actions associated with set!. A principal source of confusion is initialization_update_state!, whose name was intended to mean "update state, during initialization". However, the name seemed to be interpreted as "update state AND initialization", such that this function was overloaded with initialization activities. To fix this confusion this PR eliminates initialization_update_state!.

Another related issue is that set! was being misinterpreted as an initial condition function that can be called only once. This is not true; the intent of the design is that set! can be called multiple times. This actually can be useful for some cases where a second call to set! may use a computation from the first call. There isn't really a use case for this as far as I can tell for ocean modeling, but it applies to other kinds of models (like atmosphere models and as a corollary, for coupled models), and I believe consistency and non-surprising behavior across the ecosystem is important.

To help resolve these inconsistencies, this PR creates a distinction between "state reconciliation" which is needed to ensure consistency between 1) the 3D velocity field and the barotropic mode and 2) between the grid metrics and surface displacement for MutableVerticalDiscretization. In particular, state reconcilation needs to be performed whenever the model state is changed --- so it can occur more often than "initialization", which occurs only once. Moreover state reconciliation is "idempotent", in that multiple calls to reconcile_state!(model) (a new function for this PR) have no additional effect.

In contrast to state reconcilation, initialization is NOT guaranteed to be idempotent, and therefore must strictly be called only once. Initialization is now performed by time_step!(simulation), which is called by run!. This also means that "bare" time-stepping with time_step!(model, dt) (ie without Simulation) is not guaranteed correct unless initialize!(model) is called beforehand. Right now this issue only applies to models that use the Lagrangian-averaged DynamicSmagorinsky closure.

Note that we also call reconcile_state!(model) during initialization (recall that reconcile_state! is idempotent; so it can be called as often as needed), and we call fill_halo_regions! on prognostic variables as well. This resolves an issue raised on #5352 where halo filling needs to be moved out of update_state! (meaning that update_state! can no longer fulfill the role of a complete auxiliary state update). After this PR, a total auxiliary state update requires calling both reconcile_state! (which is not called during time-stepping), and update_state! which is called during time-stepping.

In summary this PR

• Removes the confusing initialization_update_state! function, replacing it with a clear separation of concerns
• Introduces reconcile_state! — ensures auxiliary state (barotropic velocities, vertical coordinate σ) is consistent with prognostic fields after external mutation (e.g. via set!)
• Renames initialize_free_surface! → reconcile_free_surface! and initialize_vertical_coordinate! → reconcile_vertical_coordinate! to reflect their true role as reconciliation, not one-time initialization
• Renames maybe_initialize_state! → maybe_prepare_first_time_step! (calls only update_state! at iteration 0 as a safety net for bare model time-stepping)
• Adds reconcile_state kwarg to set! for advanced users
• Updates model interface documentation with idempotency requirements
• Bumps version to 0.106.1

Function roles after this PR

Closes discussion from #5352.

Test plan

• Smoke tests: model construction, set!, SplitExplicit barotropic mode, Simulation.run!, bare time_step!
• HFSM tests: 152 passed, 7 broken (pre-existing)
• Simulation tests: 55/55 passed
• Time stepping tests: 118 passed, 2 broken (pre-existing)
• Reactant HFSM tests: 2 errors (pre-existing MLIR failures, same on main)
• Multi-region / CubedSphere tests (running)
• CI

🤖 Generated with Claude Code