Make thread_number / number_of_threads an opt-in pair like the instances pair

Author: climbfuji

capgen-ng/ccpp_capgen_ng.py

@@ -689,21 +689,44 @@ def _load_metadata_files(
     ('group_name',               'character', 'drives per-group dispatch inside ccpp_physics_* (each suite_cap emits a select case on this name)'),
     ('horizontal_loop_begin',    'integer',   'lower horizontal slice bound at scheme call sites'),
     ('horizontal_loop_end',      'integer',   'upper horizontal slice bound at scheme call sites'),
-    ('thread_number',            'integer',   'current thread number (pass 1 if single-threaded)'),
-    ('number_of_threads',        'integer',   'total thread count (pass 1 if single-threaded)'),
     ('number_of_physics_threads','integer',   'physics-internal thread budget (pass 1 if unused)'),
     ('ccpp_error_code',          'integer',   'CCPP error flag'),
     ('ccpp_error_message',       'character', 'CCPP error message'),
 ]
-
-# Optional control variables that must be declared as a *pair*.  Hosts that
-# need a multi-instance API declare both ``instance_number`` (the index) and
-# ``number_of_instances`` (the bound).  Hosts that don't may omit both; the
-# generator will emit a single-instance API and dimension all per-instance
-# arrays to length 1.  Declaring exactly one is an error.
+# NOTE: the threading index/count (``thread_number`` / ``number_of_threads``)
+# is NOT required — it is a paired-optional control pair, fully symmetric with
+# (``instance_number`` / ``number_of_instances``); see
+# ``_PAIRED_OPTIONAL_CTRL_VARS`` below.  ``number_of_physics_threads`` is a
+# separate, unpaired scheme-facing scalar that stays unconditionally required.
+
+# Paired-optional control variables.  Each entry is an (index, count) pair:
+# the host declares BOTH members (in ``type=control``) or NEITHER; declaring
+# exactly one is a hard error.  Declaring a pair opts the host into that
+# multi-<X> API — the index flows as a per-call control dummy and the count
+# gives the bound.  When a pair is absent the public API drops both args and
+# the framework uses literal ``1`` wherever the index would appear.  A host
+# variable may be dimensioned by the count standard name only when its pair is
+# declared (otherwise the resolver's scalar-index collapse raises — it needs
+# the index variable in scope).
+#
+# The two pairs are fully symmetric (decision 2026-06-09):
+#   * (instance_number, number_of_instances) — multi-instance API.  The
+#     framework reads ``number_of_instances`` at register/init to size its
+#     own per-instance state (``ccpp_suite_data(:)``, ``ccpp_group_state(:)``).
+#   * (thread_number, number_of_threads) — multi-threading API.
+#     ``thread_number`` indexes host-owned per-thread containers;
+#     ``number_of_threads`` is carried as a control dummy (the framework owns
+#     no per-thread state yet, so its value is not consumed — kept for symmetry
+#     with ``number_of_instances`` and future per-thread sizing).
+# (A chunk/block index is intentionally NOT a control pair: capgen-ng's
+# slice-based design passes the current chunk as a horizontal range via
+# horizontal_loop_begin/end, so no scheme ever indexes by chunk inside a call.)
+# Each entry: (index std_name, count std_name, index description, count description).
 _PAIRED_OPTIONAL_CTRL_VARS = [
-    ('instance_number',     'integer', 'current model instance index'),
-    ('number_of_instances', 'integer', 'total number of model instances'),
+    ('instance_number', 'number_of_instances',
+     'current model instance index', 'total number of model instances'),
+    ('thread_number',   'number_of_threads',
+     'current thread index', 'total thread count'),
 ]
 
 
@@ -775,39 +798,58 @@ def _check_control_var(std_name, expected_type, description, required: bool) ->
     for std_name, expected_type, description in _REQUIRED_CTRL_VARS:
         _check_control_var(std_name, expected_type, description, required=True)
 
-    # Paired optional: both ``instance_number`` (the per-call index) and
-    # ``number_of_instances`` (the bound, used at register time to size
-    # the per-instance state arrays) live in ``type=control``.  Symmetric
-    # with the (thread_number, number_of_threads) pair.  Either both
-    # declared or neither.
-    _check_control_var(
-        'instance_number', 'integer',
-        'current model instance index', required=False,
-    )
-    _check_control_var(
-        'number_of_instances', 'integer',
-        'total number of model instances', required=False,
-    )
+    # Paired-optional control pairs (see _PAIRED_OPTIONAL_CTRL_VARS): for each
+    # (index, count) pair the host declares both members in a type=control
+    # table or neither.  Declaring exactly one is an error.  Both pairs —
+    # (instance_number, number_of_instances) and (thread_number,
+    # number_of_threads) — are validated identically.
+    for idx_name, cnt_name, idx_desc, cnt_desc in _PAIRED_OPTIONAL_CTRL_VARS:
+        _check_control_var(idx_name, 'integer', idx_desc, required=False)
+        _check_control_var(cnt_name, 'integer', cnt_desc, required=False)
+
+        idx_present = host_dict.get(idx_name) is not None
+        cnt_present = host_dict.get(cnt_name) is not None
+        if idx_present ^ cnt_present:
+            present, missing = (
+                (idx_name, cnt_name) if idx_present else (cnt_name, idx_name)
+            )
+            errors.append(
+                "Host '{}' declares '{}' in a type=control table but is "
+                "missing its paired variable '{}' (which must also be in a "
+                "type=control table).\n"
+                "  '{}' and '{}' are a paired-optional control pair: declare "
+                "both members to opt into that API, or neither.".format(
+                    host_name, present, missing, idx_name, cnt_name,
+                )
+            )
 
-    inst_present  = host_dict.get('instance_number')  is not None
-    ninst_present = host_dict.get('number_of_instances') is not None
-    if inst_present ^ ninst_present:
-        present, missing = (
-            ('instance_number', 'number_of_instances')
-            if inst_present
-            else ('number_of_instances', 'instance_number')
-        )
-        errors.append(
-            "Host '{}' declares '{}' (in a type=control table) but is "
-            "missing the paired variable '{}' (which must also be in a "
-            "type=control table).\n"
-            "  Declare both for a multi-instance API, or neither for a "
-            "single-instance API.".format(host_name, present, missing)
-        )
+    # Control-table allowlist: a type=control table may declare ONLY the
+    # framework's known control variables — the unconditionally required set
+    # plus the members of the paired-optional pairs.  Anything else in a
+    # type=control table is a hard error.  Host-specific quantities that
+    # schemes consume belong in a type=host table; the subcycle loop variables
+    # (ccpp_loop_counter / ccpp_loop_extent) are generator-owned locals the
+    # host never declares.
+    allowed_control = {name for name, _type, _desc in _REQUIRED_CTRL_VARS}
+    for idx_name, cnt_name, _idesc, _cdesc in _PAIRED_OPTIONAL_CTRL_VARS:
+        allowed_control.add(idx_name)
+        allowed_control.add(cnt_name)
+    for std_name, entry in sorted(host_dict.items()):
+        if entry.is_control and std_name not in allowed_control:
+            errors.append(
+                "Variable '{}' is declared in a type=control table for host "
+                "'{}' but is not a recognized framework control variable.\n"
+                "  A type=control table may declare only: {}.\n"
+                "  If '{}' is a host quantity that schemes consume, declare it "
+                "in a type=host table instead.".format(
+                    std_name, host_name, ', '.join(sorted(allowed_control)),
+                    std_name,
+                )
+            )
 
     if errors:
         raise CCPPError(
-            "Host '{}' is missing required control variables:\n\n{}".format(
+            "Host '{}' has invalid control-variable metadata:\n\n{}".format(
                 host_name,
                 '\n\n'.join("ERROR: " + e for e in errors),
             )

capgen-ng/generator/group_cap.py

@@ -57,8 +57,8 @@
     'group_name',
     'horizontal_loop_begin',
     'horizontal_loop_end',
-    'thread_number',
-    'number_of_threads',
+    'thread_number',              # paired-optional (with number_of_threads); ordered here when declared
+    'number_of_threads',          # paired-optional; ordered here when declared
     'number_of_physics_threads',
     'ccpp_error_code',
     'ccpp_error_message',

capgen-ng/metadata/registered_dimensions.py

@@ -140,9 +140,11 @@
     'number_of_instances': 'instance_number',
 
     # Per-thread DDT containers (e.g. ``physics%Interstitial(thread_number)``)
-    # — the host's openmp-thread index.  ``thread_number`` is a required
-    # control variable (see doc/migration.md §3.1), so any host using
-    # this dim already has the paired index in scope.
+    # — the host's openmp-thread index.  (thread_number, number_of_threads) is
+    # a paired-optional control pair (see ccpp_capgen_ng._PAIRED_OPTIONAL_CTRL_VARS
+    # and doc/migration.md §3.1).  A host that dimensions a variable by
+    # ``number_of_threads`` MUST declare the pair — otherwise the collapse
+    # below cannot find ``thread_number`` and raises.
     'number_of_threads': 'thread_number',
 }
 

capgen-ng/metadata/variable_resolver.py

@@ -108,13 +108,13 @@ def _split_local_name(local_name: str):
     """Split a local name into (base, subscript) tuple.
 
     For plain identifiers returns (local_name, '').
-    For slice expressions like ``chunk_begin(ccpp_chunk_number)`` returns
-    (``'chunk_begin'``, ``'ccpp_chunk_number'``).
+    For slice expressions like ``field(idx)`` returns
+    (``'field'``, ``'idx'``).
 
-    >>> _split_local_name('chunk_begin')
-    ('chunk_begin', '')
-    >>> _split_local_name('chunk_begin(ccpp_chunk_number)')
-    ('chunk_begin', 'ccpp_chunk_number')
+    >>> _split_local_name('field')
+    ('field', '')
+    >>> _split_local_name('field(idx)')
+    ('field', 'idx')
     >>> _split_local_name('q(:,:,index_of_water_vapor_specific_humidity)')
     ('q', ':,:,index_of_water_vapor_specific_humidity')
     """
@@ -134,11 +134,11 @@ def _resolve_subscript(subscript: str, host_dict: Dict[str, 'HostVarEntry']) ->
 
     >>> from collections import namedtuple
     >>> E = namedtuple('E', ['local_name'])
-    >>> d = {'ccpp_chunk_number': E('inst_num')}
-    >>> _resolve_subscript('ccpp_chunk_number', d)
-    'inst_num'
-    >>> _resolve_subscript(':, ccpp_chunk_number', d)
-    ':, inst_num'
+    >>> d = {'thread_number': E('thrd_no')}
+    >>> _resolve_subscript('thread_number', d)
+    'thrd_no'
+    >>> _resolve_subscript(':, thread_number', d)
+    ':, thrd_no'
     >>> _resolve_subscript('1', d)
     '1'
     """

doc/briefing.md

@@ -110,7 +110,9 @@ For each scheme arg:
 - `ccpp_validator.py` — the standalone Fortran-vs-metadata checker.
   The ONE place capgen-ng parses Fortran.  Run by developers /
   CMake before generation.  Checks per-arg `intent`, `type`, `kind`,
-  and dimension rank; `character len=*` is a wildcard; DDT and
+  and dimension rank; character length must match exactly
+  (`len=*`↔`len=*`, `len=N`↔`len=N`, no wildcard; old-style F77
+  `character*N` / `character*(*)` parsed); DDT and
   `external:<module>:<typename>` types compare against the Fortran
   `type(name)` wrapper.  `optional` is asymmetric: metadata
   `optional=True` against a Fortran-required dummy is an error; the
@@ -200,11 +202,23 @@ Every host MUST declare scalar integers (and one character) with
 these CCPP standard names:
 
 - `suite_name`, `horizontal_loop_begin`, `horizontal_loop_end`,
-  `thread_number`, `number_of_threads`, `number_of_physics_threads`,
-  `ccpp_error_code`, `ccpp_error_message`.
+  `number_of_physics_threads`, `ccpp_error_code`, `ccpp_error_message`.
 
-Optional (paired): `instance_number` (control) +
-`number_of_instances` (host).
+**Two paired-optional control pairs** — declare *both* members of a
+pair (in `type = control`) or *neither*; declaring exactly one is a
+hard error:
+
+- `instance_number` + `number_of_instances` → opt into the
+  multi-instance API.
+- `thread_number` + `number_of_threads` → opt into the multi-threading
+  API.
+
+The two pairs are fully symmetric.  Declaring a pair makes the index a
+per-call control argument; omitting it drops both args and the
+framework uses literal `1` where the index would go.  A host variable
+may be dimensioned by `number_of_instances` / `number_of_threads` only
+when its pair is declared (otherwise the scalar-index collapse can't
+find the index variable and errors).
 
 ### 6.5 DDT-instance variables with scalar-index dims
 
@@ -387,7 +401,8 @@ don't rebuild downstream objects unless something actually moved.
 - **Validator** now checks per-argument `intent`, `type`, `kind`, and
   dimension rank in addition to the original name/count check.
   Asymmetric `optional` rule, DDT + `external:<module>:<typename>`
-  type normalisation, character `len=*` wildcard.
+  type normalisation, exact character-length match (no `len=*`
+  wildcard; old-style F77 `character*N` parsed).
 - **Resolver cross-metadata checks** (late 2026-05-20): host/scheme
   (and suite-owned-var first-writer/follow-on) consistency on type,
   rank, and per-position dimension entries.  Default lower bound has

doc/constituents.md

@@ -600,28 +600,28 @@ constituent array into the suite's `<suite>_dynamic_constituents`
 buffer (USE'd from `ccpp_host_constituents`):
 
 ```fortran
+! Outer wrapper sized to number_of_instances on first call (any instance).
 if (.not. allocated(<suite>_dynamic_constituents)) then
-  ! First-instance-only two-pass count + populate.
-  num_consts = 0
-  call <scheme1>_register(scheme_consts=scheme_consts, ...)
-  num_consts = num_consts + size(scheme_consts, 1)
-  deallocate(scheme_consts)
-  ...
-  allocate(<suite>_dynamic_constituents(num_consts))
-  num_consts = 0
-  call <scheme1>_register(scheme_consts=scheme_consts, ...)
-  do i = 1, size(scheme_consts, 1)
-    <suite>_dynamic_constituents(num_consts + i) = scheme_consts(i)
-  end do
-  num_consts = num_consts + size(scheme_consts, 1)
-  deallocate(scheme_consts)
-  ...
+  allocate(<suite>_dynamic_constituents(number_of_instances))
 end if
+
+! Single pass: call each scheme's _register EXACTLY ONCE and append its
+! returned array to THIS instance's slot.
+allocate(<suite>_dynamic_constituents(inst)%items(0))
+call <scheme1>_register(dyn_const=scheme_consts, ...)
+if (errflg /= 0) return
+<suite>_dynamic_constituents(inst)%items = &
+    [<suite>_dynamic_constituents(inst)%items, scheme_consts]
+deallocate(scheme_consts)
+! ... one block like the above per constituent-registering scheme ...
 ```
 
-The buffer is **shared across instances** (registration is identical
-per instance); only the first instance to call `<suite>_register`
-populates it.  The host-wide merge happens in
+Each instance owns its own `%items` slot (the per-instance buffer, so
+`ccpp_register_constituents` can `set_const_index` independently per
+instance); the suite state-machine guard ensures each instance populates
+it exactly once.  Each scheme's `_register` is called **exactly once** —
+it may safely allocate persistent module state (the earlier two-pass
+count+copy called it twice).  The host-wide merge happens in
 `ccpp_register_constituents`.
 
 ### Group-cap call sites