Draft: DMPlexTransform: mark the cells whose source cell was genuinely split

Stacked on !9414 — review against pbrubeck/pcpatch-coloring, not main.

An adaptively refined mesh had no way to say which of its cells are actually new, and nothing in PETSc retained the coarse-to-fine cell relation from Python: DMGetCoarseDM() is only set by DMCoarsen(), never by DMRefine(); DMPlexGetRegularRefinement() is a flag with no map; DMPlexGetSubpointMap() is for submeshes; the DMPlexSetTree() family is the non-conforming hanging-node mechanism and adaptation never populates it; and -dm_adaptor mmg/parmmg/pragmatic retains nothing at all. DMPlexTransform's bindings stopped at create/setType/setDM/setUp/apply.

• DMPlexTransformCreateSplitCellLabel(tr, dm, &label) marks the cells of a transformed mesh whose source cell produced more than one cell.
• That is a larger set than DMPlexTransformGetActive() returns, which is only the cells that were flagged: DMPLEXREFINESBR splits further cells to restore conformity, and those are refined just as genuinely.
• The man page documents the recipe for driving a local smoother: mark the split cells, DMPlexLabelComplete() to add their closure — which is exactly the entities whose star contains a refined cell — then PCPatchSetConstructLabel() from !9414.
• petsc4py gains DMPlex.setSaveTransform(), getSaveTransform(), getTransform(), and DMPlexTransform.getSourcePoint(), getActive(), setActive(), createSplitCellLabel(). Together these give both the split-cell label and the child-parent cell maps from one object: loop fine cells with getSourcePoint() for fine-to-coarse, loop coarse cells over replicas for coarse-to-fine.

Options

No new options. The prerequisite is the existing -dm_plex_save_transform (DMPlexSetSaveTransform()): the transform that produced a mesh is only reachable afterwards if it was saved, and a hierarchy is a chain of transforms, each pinning its coarse mesh, rather than one tree. The label reaches the user through -pc_patch_construct_label from !9414.

Tests were added in src/dm/impls/plex/tests/ex105.c, covering refine_sbr and refine_regular.

AI was used to draft this change (Claude Code, Opus 5).