refactor(#299) rename to incidence/emergence/specular and adopt pre-v1.0 no-deprecation policy#302
Merged
Merged
Conversation
…ate aliases) Add 'incidence' and 'emergence' as the canonical surface-frame reference-constraint names. The legacy names 'alpha_i' and 'beta_out' are kept as forwarding aliases that emit DeprecationWarning at every entry point and canonicalize to the new names before storage. mode.py: REFERENCE_NAMES gains the canonical names and retains the legacy ones as deprecated; _DEPRECATED_REFERENCE_NAME_ALIASES maps each legacy spelling to its canonical form. ReferenceConstraint.__init__ canonicalizes on construction; ConstraintSet.with_constraint_values accepts the legacy kwargs as aliases (only when the canonical constraint is actually present, so a genuine typo still surfaces as KeyError rather than a confusing deprecation followed by KeyError). forward.py: _OUTPUT_EXTRA_KEYS extended with canonical names plus legacy aliases so existing extras-dict declarations continue to receive computed values. The computers dict routes both spellings through the same callable. _solve_surface and _surface_residual dispatch on canonical names only (legacy names cannot reach them because they are canonicalized upstream). diffractometer.py: required_reference_vector dispatches on canonical names; docstring table updated. benchmark.py: _prepare_mode surface-mode branch dispatches on canonical names. Tests: parametrized rows in test_reference_constraint_construction and test_with_constraint_values_replaces_values switch to canonical names; new test_reference_constraint_deprecated_name_canonicalized and test_with_constraint_values_accepts_deprecated_alias_kwarg cover the deprecation-alias paths. Two failing assertion strings in test_with_constraint_values_unknown_key_raises_KeyError updated for the renamed constraint. Deprecation infrastructure is tagged 'REMOVE-AT-V1.0:' for the release-time cleanup tracked by #301. Contributed by: OpenCode (argo/claudeopus47)
Originally planned as a separate Step 3 in the form of an aliasing _ExtrasDict that forwards alpha_i / beta_out reads and writes to the canonical incidence / emergence slots. That design fought the dict-bulk-copy fast path used by the ConstraintSet constructor and the YAML loader, and was solving a problem (out-of-tree callers reading result.extras['alpha_i'] after the YAML migration) that a much smaller back-fill in _populate_output_extras solves directly. After populating each declared canonical output slot, mirror the list into the corresponding legacy slot regardless of whether the legacy slot was declared in the mode. The mirror uses dict.__setitem__ so it bypasses any future _ExtrasDict overrides and does not emit spurious deprecation warnings on internal writes. Adds a regression test that builds a mode declaring only the canonical slots (incidence, emergence) and verifies the legacy slots (alpha_i, beta_out) are populated by the back-fill rather than by the main computer-dict loop. Marked REMOVE-AT-V1.0 for the cleanup tracked by #301. Contributed by: OpenCode (argo/claudeopus47)
Loader: new _rewrite_legacy_reference_names() walks the parsed
document, rewrites legacy reference-constraint names ('alpha_i' /
'beta_out') and extras-dict keys to the canonical names ('incidence'
/ 'emergence'), and emits one DeprecationWarning per file naming the
source. Performed before constraint construction so the downstream
ReferenceConstraint.__init__ never sees a legacy name and the
per-constraint warnings introduced in the first commit on this branch
do not fire for YAML-loaded geometries.
JSON schema (geometries/schema.json): the reference.name enum now
lists the canonical names first. Legacy names are retained as
accepted values so unmigrated out-of-tree YAML continues to validate.
A description field on the enum documents the deprecation and points
at issue #299. No schema_revision bump: the change is backward
compatible at the schema level and the deprecation-warning channel
already delivers the migration signal.
Packaged YAML files (psic, sixc, zaxis, s2d2): every reference
constraint name and every extras-dict key migrated to the canonical
spelling. Two YAML-comment occurrences of 'alpha_i' as a symbol name
in psic.yml updated to 'incidence' for accuracy. Mode names
(fixed_alpha_i_*, fixed_beta_out_*, fixed_alpha_i_fixed_chi_fixed_phi)
are out of scope and untouched: mode names are a separate identifier
axis from the reference-constraint vocabulary.
test_regression_issue_267.py: 26 hand-built Python references
bulk-renamed to match the migrated YAML so the declarative-vs-reference
equivalence check still passes.
test_geometry_loader.py: three new tests cover the loader rewriting
path — single-warning-per-file, drops-legacy-when-mixed-with-canonical,
and skips-rewriting-when-already-canonical.
All deprecation infrastructure tagged 'REMOVE-AT-V1.0:' for the
release-time cleanup tracked by #301.
Contributed by: OpenCode (argo/claudeopus47)
Complete the Option D method-name rename that earlier commits on this branch had quietly skipped. Canonical names match the constraint-string vocabulary established by the first commit: surface.alpha_i() -> surface.incidence() surface.alpha_f() -> surface.emergence() AdHocDiffractometer.alpha_i() -> AdHocDiffractometer.incidence() AdHocDiffractometer.alpha_f() -> AdHocDiffractometer.emergence() reference.exit_angle() -> reference.emergence_angle() The legacy spellings are kept as forwarding stubs that emit DeprecationWarning on every call and delegate to the canonical implementation. reference.incidence_angle() is already English and already canonical-aligned; its internal call is updated to use the canonical geometry method. Internal callers updated: forward.py's _populate_output_extras and _surface_residual now import emergence_angle; surface.py's is_specular and is_evanescent call the canonical incidence/emergence functions directly; diffractometer.py docstrings naming the methods updated. Tests: test_surface.py's 13 call sites renamed to canonical methods; four new deprecation-cycle tests cover the alpha_i/alpha_f forwarders (both the geometry method and the standalone surface-module function variants). test_reference.py renamed its exit_angle calls and test function names to emergence_angle; one new test covers the exit_angle forwarder. test_regression_issue_292.py updated. test_mode.py adds test_reference_constraint_from_dict_accepts_legacy_name to pin the legacy-session round-trip contract. All deprecation infrastructure tagged REMOVE-AT-V1.0 for the cleanup tracked by #301. Contributed by: OpenCode (argo/claudeopus47)
…->specular YAML mode keys: fixed_alpha_i_* -> fixed_incidence_*, fixed_beta_out_* -> fixed_emergence_*, alpha_eq_beta_* -> specular_*, fixed_alpha_zaxis / fixed_beta_zaxis -> fixed_incidence_zaxis / fixed_emergence_zaxis. Constraint: a_eq_b -> specular. ReferenceConstraint canonicalizes the deprecated alias; value-check and dispatch sites in mode.py, forward.py, diffractometer.py, benchmark.py migrate to the canonical 'specular' name. ModeDict: new _DEPRECATED_MODE_NAME_ALIASES map and _canonicalize_mode_name helper. ModeDict.__getitem__ / __setitem__ / __delitem__ canonicalize legacy mode names with DeprecationWarning; __contains__ accepts legacy names silently. AdHocDiffractometer.mode_name setter canonicalizes so the getter never reports a deprecated name. Tests: 137 substitutions across nine test files bulk-renamed to the canonical mode names and constraint name. Existing alias-cycle parametrize blocks extended to cover a_eq_b -> specular. New test_modedict_legacy_mode_name_canonicalized (3 parametrized cases) and test_geometry_mode_name_setter_canonicalizes_legacy_alias. Docs (43 substitutions across 10 files): mode-name and constraint-name mentions migrated to canonical throughout the howto/, geometries/, glossary.md, concepts.md, and reference/declarative_geometry_schema.md. All deprecation infrastructure tagged REMOVE-AT-V1.0 for the cleanup tracked by #301. Contributed by: OpenCode (argo/claudeopus47)
… infrastructure Establishes the project's pre-v1.0 operating directives in AGENTS.md and removes every deprecation-cycle artefact accumulated during this PR (alias maps, forwarder methods/functions, alias-aware loader, mode-name canonicalization, deprecation tests) plus the comparable infrastructure introduced by the merged PR #300 / #298 (`azimuthal_reference` property / kwarg / from_dict fallback / test block). AGENTS.md: new 'Operating directives (pre-v1.0)' section. Five directives: no deprecation cycles; scope is the issue; no volunteered follow-up issues; response length matches the request; when in doubt, ask one short question. Pre-commit: new local pygrep hook 'no-pre-v1.0-deprecations' forbids REMOVE-AT-V1.0, DeprecationWarning, and _DEPRECATED_*_ALIASES patterns in src/ and tests/. Removed in src/: - mode.py: _DEPRECATED_REFERENCE_NAME_ALIASES, _DEPRECATED_MODE_NAME_ALIASES, _canonicalize_mode_name, ReferenceConstraint.__init__ alias canonicalization, with_constraint_values alias-kwarg block, ModeDict alias overrides - diffractometer.py: alpha_i / alpha_f deprecated methods, azimuthal_reference property + constructor kwarg + from_dict legacy-key fallback, mode_name setter canonicalization - surface.py: alpha_i / alpha_f deprecated functions - reference.py: exit_angle deprecated function - forward.py: legacy entries in _OUTPUT_EXTRA_KEYS, legacy entries in computers dict, back-fill loop - geometry_loader.py: _rewrite_legacy_reference_names function and its call site - geometries/schema.json: legacy 'alpha_i' / 'beta_out' / 'a_eq_b' enum values Removed in tests/: - 5 ReferenceConstraint deprecation tests in test_mode.py - 7-test TestAzimuthDeprecation block in test_diffractometer.py - 3 loader-rewrite tests + fixture in test_geometry_loader.py - exit_angle deprecation test in test_reference.py - 4 method-deprecation tests in test_surface.py - back-fill test in test_regression_issue_292.py Renamed throughout: every remaining legacy-name occurrence in tests and docs migrated to the canonical incidence / emergence / specular vocabulary (72 substitutions in tests, 2 deprecation-mention paragraphs removed from glossary.md and howto/surface.md). Closes the v1.0 cleanup tracking work that issue #301 (now closed as obsolete) was created to track. QC: 2623 tests pass, 100% coverage; pre-commit clean (all hooks including the new policy hook); doc build succeeds; grep for deprecation infrastructure across src/, tests/, docs/source/ returns zero matches. Net diff: -975 lines. Contributed by: OpenCode (argo/claudeopus47)
Replace the commented-out PR #298 unreleased block (which described the now-deleted azimuthal_reference deprecation cycle) with a live unreleased section listing the actual renames landed since v0.11.1: constraints (incidence, emergence, specular), modes (fixed_incidence_*, fixed_emergence_*, specular_*), Python methods (incidence, emergence), the long-form wrapper (emergence_angle), and azimuth (#298). Adds one bullet recording the pre-v1.0 no-deprecation policy adoption. Sorted alphabetically per the AGENTS.md changelog rule. Contributed by: OpenCode (argo/claudeopus47)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Renames the surface-frame reference-constraint vocabulary, the
modes that wear those constraints, and the related Python API to
self-describing English forms:
alpha_i/beta_out/a_eq_bincidence/emergence/specularfixed_alpha_i_*/fixed_beta_out_*/alpha_eq_beta_*/fixed_alpha_zaxis/fixed_beta_zaxisfixed_incidence_*/fixed_emergence_*/specular_*/fixed_incidence_zaxis/fixed_emergence_zaxisAdHocDiffractometermethods.alpha_i()/.alpha_f().incidence()/.emergence()surfacemodule functionsalpha_i()/alpha_f()incidence()/emergence()referencelong-form wrapperexit_angle()emergence_angle()Also adopts a project-wide pre-v1.0 no-deprecation policy in
AGENTS.md (no forwarding aliases, no
DeprecationWarningemitters,no alias maps) and enforces it via a new pre-commit hook
(
no-pre-v1.0-deprecations). Removes the deprecation infrastructurethat had accumulated in the earlier commits on this branch, and
removes the comparable infrastructure introduced by the merged PR
#298 (
azimuthal_referenceproperty, constructor kwarg,from_dictlegacy-key fallback,
TestAzimuthDeprecationblock). Theazimuthrename itself is preserved; only the deprecation alias is removed.
The pre-commit hook ensures future PRs cannot accidentally
reintroduce alias infrastructure while the project is still pre-v1.0.
Net diff: -99 lines (622 added, 721 removed). Tests: 2623 passed
at 100% coverage; slow benchmark: 3 passed; docs build clean.
Contributed by: OpenCode (argo/claudeopus47)