[PLACEHOLDER] ccpp-capgen-ng: a unified successor to ccpp-prebuild and ccpp-capgen

[climbfuji]

Description

This is a placeholder for a forthcoming pull request.

ccpp-capgen-ng is a prototype of a potential next-generation code generator for the CCPP framework. It is not a criticism of the existing tools — both ccpp-prebuild and ccpp-capgen have served their respective communities well and embody years of careful design. This project attempts to synthesize the strengths of both: the performance of ccpp-prebuild and the metadata richness and feature set of ccpp-capgen, while also taking advantage of relaxed code-generator requirements that have emerged over time and lessons learned from operating both tools in development, research, and production. It also aims to resolve several outstanding issues that have been blocking progress toward a long-discussed unification of the two code generators.

Supporting documents — including a redesign analysis, the LLM prompt used to bootstrap development, developer and user documentation, and a migration guide — will be provided as part of the draft pull request.

The code was developed with the assistance of an LLM (Claude, by Anthropic) as a coding partner. Where possible, existing code was reused and repackaged.

A pull request will follow shortly. Feedback and questions are welcome.

Testing

The following tests and features are currently supported by ccpp-capgen-ng:

• Former ccpp-capgen tests:
  • advection
  • capgen_ng
  • ddthost
  • nested_suite
  • var_compat
• Former ccpp-prebuild tests:
  • chunked_data
  • blocked-data not supported in capgen or capgen-ng
  • opt_arg
• Newly added features/tests:
  • multi-instances
• capgen-ng unit testing framework
  • 1200+ unit and docstring tests
• Host model integration
  • CCPP-SCM in progress
    • Feature/capgen ng climbfuji/ccpp-scm#3
    • Feature/capgen ng climbfuji/ccpp-framework#9
    • Feature/capgen ng climbfuji/ccpp-physics#21
    • Update module_mp_tempo_params.meta for capgen-ng climbfuji/TEMPO#1
    • Status 2026/05/14: all suites build, all manually run tests (a sample of all permutations) run to completion
  • CAM-SIMA todo
  • UFS todo
  • NEPTUNE in progress

Issues

A list of issues that will be addressed with this issue will be provided in the associated pull request.

WORK IN PROGRESS

Addressing this issue will also address/close the following issues if/when the participating host models switch to capgen-ng:

• Weird Capgen fortran parsing error? #757
• Bug in capgen (test/capgen_test) ? surface_air_pressure outvar in ddt_suite #755
• Document --kind-type in ccpp_capgen.py CLI/help, and consider reversing the syntax for external kind modules #754
• Remove unused metadata attribute state_variable #753
• capgen: Add capability and test for passing mpi communicator as a flat field #751
• capgen: case-sensitivity when comparing metadata to Fortran #746
• Bug in scripts/file_utils.py / move_modified_files routine #744
• Unallocated fields passed into Group Caps #690
• Capgen performance when using many suites #688
• Add support for MPI_Comm (mpi08) object in capgen #686
• Transition UFS weather model to Capgen #682
• Transition CCPP-SCM to Capgen #680
• Transition NEPTUNE to capgen #679
• Enhanced/Expanded Testing  #595
• capgen's Fortran parser does not allow array bounds which are not Fortran identifiers #588
• Add "number of instances" dimension to module-level variables to support multi-instance usage #561
• capgen: check handling of type attribute for ddts #516

To check/may not be implemented yet:

• capgen Fortran parser does not accept internal DDTs as part of a registered DDT #749
• capgen: Invalid character declaration, 'character(len=nf_file_length) ' #748
• capgen: dimension specifier foo(N) is not the same as foo(1:N) in Fortran code #747
• Errors when integer variable is output from one phase and used as an interstitial dimension in another #681
• CCPP Framework to provide API calls for suite inspection by host #380
• Fortran/metadata comparison incorrectly reporting bug when comparing Fortran variable declarations and metadata for derived types #360

Working towards:

• Simplification of ccpp-framework code #737

Supporting Materials

Date and time are all local U.S. Mountain Time. Subsections are sorted from newest to oldest.

LLM-Generated Drafts (20260513T0733/latest)

The documents below were produced by Claude during development and have not yet been formally reviewed. They are shared for transparency and to give context for the design decisions made. They should be treated as starting points rather than authoritative references.

constituents_20260513T0733.md
constituents_overhaul_20260513T0733.md
migration_20260513T0733.md
redesign_analysis_20260513T0733.md
redesign_prompt_20260513T0733.md

Comparison: size of code base:

LLM-Generated Drafts (202060505T2044/initial)

The documents below were produced by Claude during development and have not yet been formally reviewed. They are shared for transparency and to give context for the design decisions made. They should be treated as starting points rather than authoritative references.

redesign_analysis_original_202060505T2044.md
redesign_prompt_original_20260505T2044.md