From 44febed76f580338f4100addb8add96dbd0d8837 Mon Sep 17 00:00:00 2001 From: Prithwish Mukherjee Date: Thu, 24 Sep 2026 13:55:15 +0530 Subject: [PATCH 1/7] feat: Add Agents.md --- .github/copilot-instructions.md | 27 +++ AGENTS.md | 67 +++++++ devel/agents/architecture.md | 305 ++++++++++++++++++++++++++++++++ devel/agents/testing.md | 49 +++++ devel/agents/workflows.md | 32 ++++ 5 files changed, 480 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 AGENTS.md create mode 100644 devel/agents/architecture.md create mode 100644 devel/agents/testing.md create mode 100644 devel/agents/workflows.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000000..2a86a93f2ad6 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,27 @@ +# GitHub Copilot instructions for PyFluent + +This file is intentionally minimal. The canonical project guidance lives in @AGENTS.md at the repository root. Use that file as the single source of truth for setup, repo map, commands, and default operating rules. + +## Required behavior + +- Read @AGENTS.md first for project orientation. +- Start with one targeted search and the smallest relevant reads. +- Prefer the closest existing test coverage over new assumptions. +- Keep fixes narrow and root-cause focused. +- Do not hand-edit generated API files without a clear, justified reason. + +## Repo-specific overrides + +- Treat `src/ansys/fluent/core` as the main runtime package. +- Treat `codegen` and generated modules as schema-driven or generation-managed code unless explicitly required otherwise. +- Use the smallest relevant pytest target; do not default to a broad suite for a small fix. +- For deeper architecture or workflow guidance, follow the links in @AGENTS.md to the docs under `devel/agents`. + +## Documentation hierarchy + +- @AGENTS.md — canonical startup and repo guidance +- @devel/agents/architecture.md — subsystem and architecture map +- @devel/agents/testing.md — validation strategy +- @devel/agents/workflows.md — contribution workflow + +This file should stay short and point to the canonical guidance rather than re-describing it. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000000..c0618104a014 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,67 @@ +# AGENTS.md + +PyFluent is the Python interface for Ansys Fluent. + +## Setup + +```bash +python -m venv .venv +# Windows +.venv\Scripts\activate +# Linux/macOS +source .venv/bin/activate +pip install -e ".[tests]" +``` + +For optional feature sets, install the relevant extras explicitly as needed, for example: + +```bash +pip install -e ".[reader,search,ui,ui-jupyter]" +``` + +## Primary objectives + +1. Provide good answers with minimal token consumption. +2. Provide accurate answers by using the correct architectural map and repo-specific guidance. + +## Commands + +```bash +python -m pytest tests +``` + +```bash +pre-commit run --all-files +``` + +## Repo map + +- `src/ansys/fluent/core` — runtime package +- `src/ansys/fluent/core/generated` — generated API code +- `codegen` — generation workflow +- `tests` — behavior and regression tests +- `doc` — docs +- `examples` — usage examples +- `devel` — repo engineering notes + +## Agent rules + +1. Start with one targeted search and the smallest relevant reads. +2. Prefer existing tests and project conventions over guessing. +3. Keep patches narrow and fix one root cause. +4. Do not hand-edit generated API files unless the workflow explicitly requires it. +5. Validate with the smallest relevant test target. +6. Prefer cheap validation first: import checks, syntax checks, and the closest non-Fluent tests. +7. Avoid large integration suites or tests that require an active Fluent session unless the change genuinely requires them. +8. If a change affects imports, package boundaries, or public APIs, check import paths and package-level exposure before escalating to heavier tests. +9. If unsure about the correct subsystem, feature mapping, or test target, ask the user instead of guessing or hallucinating. +10. Keep AGENTS.md lightweight; do not stuff all repo details here. Use the deeper docs for architecture and workflow details. + +## Deeper guidance + +- `devel/agents/architecture.md` — subsystem map +- `devel/agents/testing.md` — validation strategy +- `devel/agents/workflows.md` — contribution workflow +- `.github/copilot-instructions.md` — repo-specific Copilot overrides + +Use the deeper docs only when the task touches Fluent lifecycle, meshing/solver APIs, settings/datamodel generation, packaging, or CI behavior. diff --git a/devel/agents/architecture.md b/devel/agents/architecture.md new file mode 100644 index 000000000000..cd37d33147c2 --- /dev/null +++ b/devel/agents/architecture.md @@ -0,0 +1,305 @@ +# Architecture map for AI agents + +This document is intentionally narrow and repo-specific. It gives agents the minimum map needed to navigate PyFluent without requiring a huge root-level instruction file. + +## 1. Product shape + +PyFluent exposes a Pythonic API on top of Ansys Fluent. The architecture is organized around the layers that matter most for correctness and maintainability: + +1. Fluent launch and session management +2. Settings and datamodel surfaces +3. Generated API layer for Fluent objects and commands +4. Runtime helpers and integration code +5. Tests, docs, and examples + +The TUI-oriented command access layer is present, but it is not the primary architectural focus for most agent work. + +## 2. Key directories + +- `src/ansys/fluent/core` — primary runtime code and package entry points +- `src/ansys/fluent/core/generated` — generated API code; usually not the place for hand-written changes +- `codegen` — generation scripts and schema-driven workflows +- `tests` — behavioral validation and regression coverage +- `doc` — Sphinx docs and generated API docs +- `examples` — usage examples +- `devel` — engineering and repo notes + +## 3. High-level architectural boundaries + +### Runtime and session layer + +This is the core operational layer. It owns the Fluent session lifecycle, launch behavior, health checks, command routing, and the Python-facing abstractions that most users call. + +Typical responsibilities include: + +- launching Fluent from local or managed environments +- session lifecycle and health checks +- command dispatch and result handling +- service-level integration around Fluent operations +- settings/datamodel access wrappers + +The main entry point is `pyfluent.launch_fluent()` in the launcher module. It returns a mode-specific session such as solver or meshing variants. + +### Settings and datamodel layer + +This layer is central to correctness in PyFluent. Much of the project surface is built around structured Fluent settings, datamodel access, and generated object mappings. + +This is a high-value area for agent understanding because bugs here often affect API behavior rather than isolated UI concerns. + +### Generated API layer + +The generated API layer is tightly coupled to Fluent versioned schema and command definitions. It is often the authoritative contract for schema-driven behavior. + +Important rule: + +- generated files are often authoritative for schema-driven APIs +- hand edits are generally risky and should be justified by a generation or API contract decision + +### Field and solution data layer + +The field-data subsystem is a distinct feature area rather than a generic utility. It is exposed via `ansys.fluent.core.fields` and includes: + +- `FieldData` / `FieldDataBatch` for live field access +- `Reduction` for reduction operations +- `SolutionVariableData` / `SolutionVariableInfo` for solution-variable metadata and data access + +This layer is the primary entry point for field-level workflows and is usually validated with `test_field_data.py` and related solution-variable coverage. + +### Test and documentation layer + +The project maintains behavior-focused tests in `tests/` and documentation in `doc/` and `examples/`. These are the main validation and guidance surfaces for making safe changes. + +## 4. Feature entry points and capability map + +Use these as the first-stop map for feature work: + +- Session launch: `pyfluent.launch_fluent()` in `src/ansys/fluent/core/launcher/launcher.py` +- Solver and meshing sessions: `FluentMode.SOLVER`, `FluentMode.MESHING`, `FluentMode.PURE_MESHING`, and the session objects returned from the launch call +- Field data: `ansys.fluent.core.fields.FieldData`, `FieldDataBatch`, `Reduction`, `SolutionVariableData` +- Settings/datamodel access: session-level settings and datamodel surfaces exposed from the runtime session objects +- File transfer and persistence: file-session and transfer service modules under `src/ansys/fluent/core` + +This is the capability map agents should keep in memory before drilling into a specific module. + +## 5. Feature-by-feature inventory + +This is the practical subsystem map agents should keep in memory when working on PyFluent. + +### 5.1 Session and lifecycle + +Primary responsibility: + +- launch Fluent sessions +- manage session lifecycle and health checks +- choose solver, meshing, or specialized session modes + +Key entry points: + +- `pyfluent.launch_fluent()` in `src/ansys/fluent/core/launcher/launcher.py` +- `ansys.fluent.core.session` exports concrete session classes such as `Solver`, `Meshing`, `PureMeshing`, `FileSession`, `PrePost` +- `ansys.fluent.core.__init__` re-exports the public entry points and exposes `Fluent` as the top-level session-oriented class + +Likely validation targets: + +- `tests/test_launcher.py` +- `tests/test_launcher_remote.py` +- `tests/test_fluent_session.py` +- `tests/test_session.py` +- `tests/test_pre_post_session.py` + +Confidence: + +- High. These are repo-backed, public session entry points. + +### 5.2 Meshing workflows + +Primary responsibility: + +- meshing mode sessions +- workflow wrappers and meshing-specific operations +- transition between meshing and solver flows + +Key entry points: + +- `src/ansys/fluent/core/meshing/__init__.py` +- `src/ansys/fluent/core/session/meshing.py` and related session classes +- meshing workflow classes under the meshing package and related workflow modules + +Likely validation targets: + +- `tests/test_meshing_workflow.py` +- `tests/test_new_meshing_workflow.py` +- `tests/test_meshing_utilities.py` +- `tests/test_pure_mesh_vs_mesh_workflow.py` +- `tests/test_server_meshing_workflow.py` + +Confidence: + +- High for workflow entry points and the public meshing API surface. +- Some details are version-specific; when a workflow changes behavior by Fluent version, the generated or compatibility path should be checked before assuming a single implementation. + +### 5.3 Solver and solver-mode sessions + +Primary responsibility: + +- solver sessions and specialized solver variants +- solver-mode integration and setup +- solver-specific APIs and add-ons such as aero and icing flows + +Key entry points: + +- `src/ansys/fluent/core/solver/__init__.py` +- `src/ansys/fluent/core/session/solver.py` +- specialized session modules for solver variants and pre/post flows +- generated settings surface under `src/ansys/fluent/core/generated` + +Likely validation targets: + +- `tests/test_solution_variables.py` +- `tests/test_solvermode/` +- `tests/test_tui_api.py` +- `tests/test_public_api.py` +- `tests/test_settings_api.py` + +Confidence: + +- High for the public solver entry points and generated settings surfaces. +- Some exact internal boundaries may be generated and version-bound; this should be treated as generation-managed code unless the repo explicitly says otherwise. + +### 5.4 Fields, reductions, and solution variables + +Primary responsibility: + +- field-data access and reduction operations +- solution-variable metadata and data retrieval +- Fluent field and solution data workflows + +Key entry points: + +- `src/ansys/fluent/core/fields/__init__.py` +- `FieldData`, `FieldDataBatch`, `Reduction`, `SolutionVariableData`, and `SolutionVariableInfo` +- lower-level services in `src/ansys/fluent/core/services` and gRPC field-data service modules + +Likely validation targets: + +- `tests/test_field_data.py` +- `tests/test_solution_variables.py` +- `tests/test_physical_quantities.py` + +Confidence: + +- High. This is a well-defined feature cluster with clear public entry points and direct test coverage. + +### 5.5 Settings and datamodel surfaces + +Primary responsibility: + +- Fluent settings access +- datamodel object navigation +- settings readers and schema-backed behaviors + +Key entry points: + +- session-level settings objects exposed from the runtime session +- generated settings modules under `src/ansys/fluent/core/generated` +- settings readers and model wrappers under the core runtime package + +Likely validation targets: + +- `tests/test_settings_api.py` +- `tests/test_settings_reader.py` +- `tests/test_datamodel_api.py` +- `tests/test_datamodel_service.py` +- `tests/test_builtin_settings.py` + +Confidence: + +- High for test coverage and public API surface. +- Very high generation dependence: if a bug is schema-driven, the generated layer should be treated as the source of truth before modifying runtime wrappers. + +### 5.6 File transfer and file-session workflows + +Primary responsibility: + +- file session access +- file transfer service behavior +- case/data reader workflows +- file-backed Fluent workflows + +Key entry points: + +- `src/ansys/fluent/core/session/file.py` +- `src/ansys/fluent/core/file_transfer_service.py` +- `src/ansys/fluent/core/file_reader` and related reader modules + +Likely validation targets: + +- `tests/test_file_session.py` +- `tests/test_file_transfer_service.py` +- `tests/test_datareader.py` +- `tests/test_casereader.py` + +Confidence: + +- High for the public file-related API surface. +- Some lower-level file-transfer behavior may depend on environment and Fluent runtime setup, so these are not always the cheapest validation targets. + +### 5.7 Public API and compatibility surface + +Primary responsibility: + +- package-level exports +- deprecations and compatibility shims +- high-level user-facing API stability + +Key entry points: + +- `src/ansys/fluent/core/__init__.py` +- compatibility and deprecation layers within the core package + +Likely validation targets: + +- `tests/test_public_api.py` +- `tests/test_deprecate.py` +- `tests/test_flobject.py` + +Confidence: + +- High for visible API/compatibility behaviors. + +## 6. How to choose the right validation path + +When a patch is in doubt, prefer this order: + +1. import/syntax check +2. nearest unit-level or API-level test +3. nearest feature test cluster +4. broader Fluent-session or integration tests only if required by the feature + +Examples: + +- change in launch/session lifecycle → start with `test_launcher.py` or `test_fluent_session.py` +- change in meshing flow → use `test_meshing_workflow.py` and related meshing tests +- change in fields or solution variables → use `test_field_data.py` and `test_solution_variables.py` +- change in settings/datamodel behavior → use `test_settings_api.py` and `test_datamodel_api.py` +- change in file transfer or file reading → use the file-session and reader tests + +## 7. Agent-specific heuristics + +- If a change looks schema-driven, inspect the generated layer before editing runtime code. +- If a change affects public APIs, check tests and docs together. +- If a bug is in Fluent integration behavior, validate against the likely session/launcher and settings/datamodel path. +- If there is uncertainty about generated vs hand-authored code, search for generated markers before editing. +- When a mapping is unclear due to version-specific behavior, do not assume a single implementation; prefer the generated or compatibility-aware path and confirm with the nearest repo tests. + +## 8. Cost-aware usage guidance + +To reduce token use and improve answer quality: + +- read the local runtime and settings/datamodel entrypoints first +- search for the feature name before broad file scanning +- avoid reading the full generated tree unless the behavior is explicitly generated +- prefer the specific test file closest to the changed behavior +- treat large Fluent-session tests as escalation points, not default validation paths + +This document is a map, not a manual. It should orient the agent and keep the work focused, not replace targeted investigation. diff --git a/devel/agents/testing.md b/devel/agents/testing.md new file mode 100644 index 000000000000..d797d89ccb68 --- /dev/null +++ b/devel/agents/testing.md @@ -0,0 +1,49 @@ +# Testing strategy + +Use the smallest relevant test target that checks the changed behavior. + +## Canonical command + +```bash +python -m pytest tests +``` + +## Rules + +1. Start from the nearest test file or selection for the changed behavior. +2. Prefer real behavior validation over mock-only assertions. +3. If the change touches generated or schema-driven code, validate the downstream contract as well. +4. Do not default to a full suite for a narrow fix. +5. Prefer cheap validation first: import checks, syntax checks, and the closest non-Fluent tests. +6. Avoid large integration suites or tests requiring an active Fluent session unless the change genuinely requires them. +7. If the change affects imports, package boundaries, or public APIs, validate import paths and package exposure before escalating. +8. If a public API regression is fixed, add or update a focused test. +9. If the correct test target is unclear, ask the user instead of guessing or running broad suites. +10. Keep the first objective in mind: good answers with minimal token usage; use the cheapest validation that still checks the behavior. + +## Repo context + +The `tests` tree covers: + +- runtime API behavior +- Fluent launch and session lifecycle +- settings/datamodel access +- field data and solution-variable workflows +- meshing and solver-mode behavior +- file transfer and session persistence +- regression and compatibility checks + +## Feature-to-test map + +Use this as a quick routing guide before choosing a test target: + +- Launch and session lifecycle: `test_launcher.py`, `test_launcher_remote.py`, `test_fluent_session.py`, `test_session.py` +- Settings and datamodel API: `test_settings_api.py`, `test_settings_reader.py`, `test_datamodel_api.py`, `test_datamodel_service.py` +- Field data and solution variables: `test_field_data.py`, `test_solution_variables.py`, `test_physical_quantities.py` +- Meshing workflows: `test_meshing_workflow.py`, `test_new_meshing_workflow.py`, `test_meshing_utilities.py`, `test_pure_mesh_vs_mesh_workflow.py`, `test_server_meshing_workflow.py` +- File and transfer behavior: `test_file_session.py`, `test_file_transfer_service.py`, `test_datareader.py`, `test_casereader.py` +- API and object surfaces: `test_flobject.py`, `test_tui_api.py`, `test_rp_vars.py`, `test_public_api.py` + +This is not exhaustive, but it gives a stable map from feature area to the most likely test cluster. + +Use this structure to choose the closest validation path, not a broad one. diff --git a/devel/agents/workflows.md b/devel/agents/workflows.md new file mode 100644 index 000000000000..211881944800 --- /dev/null +++ b/devel/agents/workflows.md @@ -0,0 +1,32 @@ +# Contributor workflow + +Keep work narrow, test-driven, and repo-aware. + +## Default flow + +1. Identify the owning subsystem. +2. Search for the relevant symbols and tests. +3. Read only the tightest relevant sections. +4. Fix one root cause. +5. Run the cheapest validation that checks the changed behavior. +6. Check import paths and package-level exposure before escalating to heavier tests. +7. Avoid large Fluent-session tests unless the patch genuinely requires them. +8. If there is uncertainty about the correct feature mapping or fix site, ask the user instead of guessing. +9. Keep the primary objectives in view: minimal token consumption and high accuracy through targeted repo knowledge. +10. Summarize what changed and the evidence. + +## Repo conventions + +- Keep patches within the owning feature area. +- Prefer existing project patterns over new abstractions. +- Respect the separation between runtime code and generated code. +- Do not broaden scope for a single bug fix. + +## Escalate when the work touches + +- Fluent version compatibility +- generation or schema workflows +- packaging or release behavior +- CI or platform-specific execution + +Use the root AGENTS file as the startup brief, and the deeper docs only when the task actually needs that context. From 34eaaacb194863d46c58553e26af3aaeedbb592c Mon Sep 17 00:00:00 2001 From: Prithwish Mukherjee Date: Thu, 24 Sep 2026 14:10:18 +0530 Subject: [PATCH 2/7] feat: Add Agents.md --- .github/copilot-instructions.md | 14 +- AGENTS.md | 32 +-- devel/agents/architecture.md | 369 ++++++++------------------------ devel/agents/testing.md | 17 +- 4 files changed, 124 insertions(+), 308 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 2a86a93f2ad6..2f33c120c393 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -5,17 +5,13 @@ This file is intentionally minimal. The canonical project guidance lives in @AGE ## Required behavior - Read @AGENTS.md first for project orientation. -- Start with one targeted search and the smallest relevant reads. -- Prefer the closest existing test coverage over new assumptions. -- Keep fixes narrow and root-cause focused. -- Do not hand-edit generated API files without a clear, justified reason. +- Follow the repo rules in @AGENTS.md before expanding to deeper docs. +- Keep this file short; do not duplicate the root guidance. -## Repo-specific overrides +## Repo-specific override - Treat `src/ansys/fluent/core` as the main runtime package. -- Treat `codegen` and generated modules as schema-driven or generation-managed code unless explicitly required otherwise. -- Use the smallest relevant pytest target; do not default to a broad suite for a small fix. -- For deeper architecture or workflow guidance, follow the links in @AGENTS.md to the docs under `devel/agents`. +- Treat generated modules as schema-driven or generation-managed code unless a task explicitly requires otherwise. ## Documentation hierarchy @@ -24,4 +20,4 @@ This file is intentionally minimal. The canonical project guidance lives in @AGE - @devel/agents/testing.md — validation strategy - @devel/agents/workflows.md — contribution workflow -This file should stay short and point to the canonical guidance rather than re-describing it. +This file should stay brief and point to the canonical guidance rather than repeating it. diff --git a/AGENTS.md b/AGENTS.md index c0618104a014..495cd3542a8b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,26 +11,19 @@ python -m venv .venv # Linux/macOS source .venv/bin/activate pip install -e ".[tests]" -``` - -For optional feature sets, install the relevant extras explicitly as needed, for example: - -```bash +# optional extras pip install -e ".[reader,search,ui,ui-jupyter]" ``` ## Primary objectives -1. Provide good answers with minimal token consumption. -2. Provide accurate answers by using the correct architectural map and repo-specific guidance. +1. Good answers with minimal token consumption. +2. Accurate answers using the correct repo map and architecture. ## Commands ```bash python -m pytest tests -``` - -```bash pre-commit run --all-files ``` @@ -40,28 +33,25 @@ pre-commit run --all-files - `src/ansys/fluent/core/generated` — generated API code - `codegen` — generation workflow - `tests` — behavior and regression tests -- `doc` — docs -- `examples` — usage examples -- `devel` — repo engineering notes +- `doc` / `examples` / `devel` — docs, examples, engineering notes ## Agent rules 1. Start with one targeted search and the smallest relevant reads. 2. Prefer existing tests and project conventions over guessing. 3. Keep patches narrow and fix one root cause. -4. Do not hand-edit generated API files unless the workflow explicitly requires it. +4. Do not hand-edit generated API files unless required. 5. Validate with the smallest relevant test target. -6. Prefer cheap validation first: import checks, syntax checks, and the closest non-Fluent tests. -7. Avoid large integration suites or tests that require an active Fluent session unless the change genuinely requires them. -8. If a change affects imports, package boundaries, or public APIs, check import paths and package-level exposure before escalating to heavier tests. -9. If unsure about the correct subsystem, feature mapping, or test target, ask the user instead of guessing or hallucinating. -10. Keep AGENTS.md lightweight; do not stuff all repo details here. Use the deeper docs for architecture and workflow details. +6. Prefer cheap validation first: import checks, syntax checks, and nearby non-Fluent tests. +7. Avoid large integration or active-Fluent-session tests unless the change truly requires them. +8. If imports, package boundaries, or public APIs are affected, check import paths before escalating. +9. If the subsystem, feature mapping, or test target is unclear, ask the user instead of guessing. ## Deeper guidance - `devel/agents/architecture.md` — subsystem map - `devel/agents/testing.md` — validation strategy - `devel/agents/workflows.md` — contribution workflow -- `.github/copilot-instructions.md` — repo-specific Copilot overrides +- `.github/copilot-instructions.md` — short repo-specific pointer -Use the deeper docs only when the task touches Fluent lifecycle, meshing/solver APIs, settings/datamodel generation, packaging, or CI behavior. +Use these only when the task touches Fluent lifecycle, meshing/solver APIs, settings/datamodel generation, packaging, or CI behavior. diff --git a/devel/agents/architecture.md b/devel/agents/architecture.md index cd37d33147c2..6925b12bc484 100644 --- a/devel/agents/architecture.md +++ b/devel/agents/architecture.md @@ -1,305 +1,126 @@ # Architecture map for AI agents -This document is intentionally narrow and repo-specific. It gives agents the minimum map needed to navigate PyFluent without requiring a huge root-level instruction file. +This document is intentionally small but repo-specific. It gives agents the fastest path to the right feature area and the most relevant validation target. ## 1. Product shape -PyFluent exposes a Pythonic API on top of Ansys Fluent. The architecture is organized around the layers that matter most for correctness and maintainability: +PyFluent exposes a Pythonic API on top of Ansys Fluent. The major layers are: 1. Fluent launch and session management -2. Settings and datamodel surfaces -3. Generated API layer for Fluent objects and commands -4. Runtime helpers and integration code -5. Tests, docs, and examples - -The TUI-oriented command access layer is present, but it is not the primary architectural focus for most agent work. - -## 2. Key directories - -- `src/ansys/fluent/core` — primary runtime code and package entry points -- `src/ansys/fluent/core/generated` — generated API code; usually not the place for hand-written changes +2. Meshing and solver sessions +3. Settings and datamodel surfaces +4. Generated API layer +5. Field data, reduction, and solution-variable workflows +6. File transfer, file sessions, and reader workflows +7. Search, workflows, scheduling, remote execution, and API utilities + +## 2. Core package map + +- `src/ansys/fluent/core/__init__.py` — top-level package exports and public entry points +- `src/ansys/fluent/core/launcher` — launch orchestration and mode selection +- `src/ansys/fluent/core/session` — concrete session classes: solver, meshing, file, pre/post +- `src/ansys/fluent/core/meshing` — meshing workflows and workflow wrappers +- `src/ansys/fluent/core/solver` — solver API surface and generated settings entry points +- `src/ansys/fluent/core/fields` — field data, reduction, solution variables +- `src/ansys/fluent/core/services` — service interfaces and backend wrappers +- `src/ansys/fluent/core/file_transfer_service.py` — file transfer service +- `src/ansys/fluent/core/file_reader` — case/data file readers +- `src/ansys/fluent/core/search.py` — search API across object hierarchy +- `src/ansys/fluent/core/workflow.py`, `workflow_old.py` — workflow wrappers and compatibility paths +- `src/ansys/fluent/core/local_parametric_study.py` — parametric study support +- `src/ansys/fluent/core/scheduler` — scheduler integration +- `src/ansys/fluent/core/rest` and `src/ansys/fluent/core/ui` — REST / UI helpers +- `src/ansys/fluent/core/utils` — general utilities and setup helpers +- `src/ansys/fluent/core/generated` — generated API layer; treat as generation-managed unless a task explicitly requires otherwise - `codegen` — generation scripts and schema-driven workflows -- `tests` — behavioral validation and regression coverage -- `doc` — Sphinx docs and generated API docs -- `examples` — usage examples -- `devel` — engineering and repo notes - -## 3. High-level architectural boundaries - -### Runtime and session layer - -This is the core operational layer. It owns the Fluent session lifecycle, launch behavior, health checks, command routing, and the Python-facing abstractions that most users call. - -Typical responsibilities include: - -- launching Fluent from local or managed environments -- session lifecycle and health checks -- command dispatch and result handling -- service-level integration around Fluent operations -- settings/datamodel access wrappers - -The main entry point is `pyfluent.launch_fluent()` in the launcher module. It returns a mode-specific session such as solver or meshing variants. - -### Settings and datamodel layer - -This layer is central to correctness in PyFluent. Much of the project surface is built around structured Fluent settings, datamodel access, and generated object mappings. - -This is a high-value area for agent understanding because bugs here often affect API behavior rather than isolated UI concerns. - -### Generated API layer - -The generated API layer is tightly coupled to Fluent versioned schema and command definitions. It is often the authoritative contract for schema-driven behavior. - -Important rule: - -- generated files are often authoritative for schema-driven APIs -- hand edits are generally risky and should be justified by a generation or API contract decision - -### Field and solution data layer - -The field-data subsystem is a distinct feature area rather than a generic utility. It is exposed via `ansys.fluent.core.fields` and includes: - -- `FieldData` / `FieldDataBatch` for live field access -- `Reduction` for reduction operations -- `SolutionVariableData` / `SolutionVariableInfo` for solution-variable metadata and data access - -This layer is the primary entry point for field-level workflows and is usually validated with `test_field_data.py` and related solution-variable coverage. - -### Test and documentation layer - -The project maintains behavior-focused tests in `tests/` and documentation in `doc/` and `examples/`. These are the main validation and guidance surfaces for making safe changes. - -## 4. Feature entry points and capability map - -Use these as the first-stop map for feature work: - -- Session launch: `pyfluent.launch_fluent()` in `src/ansys/fluent/core/launcher/launcher.py` -- Solver and meshing sessions: `FluentMode.SOLVER`, `FluentMode.MESHING`, `FluentMode.PURE_MESHING`, and the session objects returned from the launch call -- Field data: `ansys.fluent.core.fields.FieldData`, `FieldDataBatch`, `Reduction`, `SolutionVariableData` -- Settings/datamodel access: session-level settings and datamodel surfaces exposed from the runtime session objects -- File transfer and persistence: file-session and transfer service modules under `src/ansys/fluent/core` - -This is the capability map agents should keep in memory before drilling into a specific module. - -## 5. Feature-by-feature inventory - -This is the practical subsystem map agents should keep in memory when working on PyFluent. - -### 5.1 Session and lifecycle - -Primary responsibility: - -- launch Fluent sessions -- manage session lifecycle and health checks -- choose solver, meshing, or specialized session modes - -Key entry points: - -- `pyfluent.launch_fluent()` in `src/ansys/fluent/core/launcher/launcher.py` -- `ansys.fluent.core.session` exports concrete session classes such as `Solver`, `Meshing`, `PureMeshing`, `FileSession`, `PrePost` -- `ansys.fluent.core.__init__` re-exports the public entry points and exposes `Fluent` as the top-level session-oriented class - -Likely validation targets: - -- `tests/test_launcher.py` -- `tests/test_launcher_remote.py` -- `tests/test_fluent_session.py` -- `tests/test_session.py` -- `tests/test_pre_post_session.py` - -Confidence: - -- High. These are repo-backed, public session entry points. - -### 5.2 Meshing workflows - -Primary responsibility: - -- meshing mode sessions -- workflow wrappers and meshing-specific operations -- transition between meshing and solver flows -Key entry points: +## 3. Feature-to-entry-point map -- `src/ansys/fluent/core/meshing/__init__.py` -- `src/ansys/fluent/core/session/meshing.py` and related session classes -- meshing workflow classes under the meshing package and related workflow modules +Use this as the first-stop lookup before reading code. -Likely validation targets: +- Launch and session lifecycle + - package: `src/ansys/fluent/core/launcher`, `src/ansys/fluent/core/session` + - entry: `pyfluent.launch_fluent()` + - tests: `tests/test_launcher.py`, `tests/test_launcher_remote.py`, `tests/test_fluent_session.py`, `tests/test_session.py`, `tests/test_pre_post_session.py` -- `tests/test_meshing_workflow.py` -- `tests/test_new_meshing_workflow.py` -- `tests/test_meshing_utilities.py` -- `tests/test_pure_mesh_vs_mesh_workflow.py` -- `tests/test_server_meshing_workflow.py` +- Meshing + - package: `src/ansys/fluent/core/meshing`, `src/ansys/fluent/core/session/meshing.py` + - entry: `pyfluent.launch_fluent(mode="meshing")`, `Meshing`, `PureMeshing` + - tests: `tests/test_meshing_workflow.py`, `tests/test_new_meshing_workflow.py`, `tests/test_meshing_utilities.py`, `tests/test_pure_mesh_vs_mesh_workflow.py`, `tests/test_server_meshing_workflow.py` -Confidence: +- Solver and solver variants + - package: `src/ansys/fluent/core/solver`, `src/ansys/fluent/core/session/solver.py` + - entry: `pyfluent.launch_fluent(mode="solver")`, `Solver`, `SolverAero`, `SolverIcing`, `PrePost` + - tests: `tests/test_solution_variables.py`, `tests/test_solvermode`, `tests/test_tui_api.py`, `tests/test_public_api.py`, `tests/test_settings_api.py` -- High for workflow entry points and the public meshing API surface. -- Some details are version-specific; when a workflow changes behavior by Fluent version, the generated or compatibility path should be checked before assuming a single implementation. +- Fields and reduction + - package: `src/ansys/fluent/core/fields` + - entry: `ansys.fluent.core.fields.FieldData`, `FieldDataBatch`, `Reduction`, `SolutionVariableData`, `SolutionVariableInfo` + - tests: `tests/test_field_data.py`, `tests/test_reduction.py`, `tests/test_solution_variables.py`, `tests/test_physical_quantities.py` -### 5.3 Solver and solver-mode sessions +- Settings and datamodel + - package: `src/ansys/fluent/core/services/object_model.py`, generated settings under `src/ansys/fluent/core/generated` + - entry: runtime session settings object tree and datamodel interfaces + - tests: `tests/test_settings_api.py`, `tests/test_settings_reader.py`, `tests/test_datamodel_api.py`, `tests/test_datamodel_service.py`, `tests/test_builtin_settings.py` -Primary responsibility: +- File transfer and file sessions + - package: `src/ansys/fluent/core/file_transfer_service.py`, `src/ansys/fluent/core/session/file.py`, `src/ansys/fluent/core/file_reader` + - entry: `FileSession`, file-transfer strategies and case/data readers + - tests: `tests/test_file_session.py`, `tests/test_file_transfer_service.py`, `tests/test_datareader.py`, `tests/test_casereader.py` -- solver sessions and specialized solver variants -- solver-mode integration and setup -- solver-specific APIs and add-ons such as aero and icing flows +- Search and API lookup + - package: `src/ansys/fluent/core/search.py` + - entry: `search(...)` + - tests: `tests/test_search.py` -Key entry points: +- Workflow and parametric study + - package: `src/ansys/fluent/core/workflow.py`, `src/ansys/fluent/core/local_parametric_study.py` + - entry: workflow objects and parametric study helpers + - tests: `tests/test_batch_ops.py`, `tests/test_scheduler.py`, `tests/test_slurm_future.py`, `tests/test_systemcoupling.py`, `tests/test_parametric` if present in the repo -- `src/ansys/fluent/core/solver/__init__.py` -- `src/ansys/fluent/core/session/solver.py` -- specialized session modules for solver variants and pre/post flows -- generated settings surface under `src/ansys/fluent/core/generated` +- Streaming, event, and service plumbing + - package: `src/ansys/fluent/core/services/streaming_services`, `src/ansys/fluent/core/services` + - entry: streaming services, events, monitor and transcript integrations + - tests: `tests/test_events_manager.py`, `tests/test_streaming_services.py` -Likely validation targets: +- Batch operations and remote execution + - package: `src/ansys/fluent/core/services/batch_ops.py`, `src/ansys/fluent/core/scheduler`, `src/ansys/fluent/core/docker` + - entry: batch operations and remote/scheduler launch flows + - tests: `tests/test_batch_ops.py`, `tests/test_scheduler.py`, `tests/test_slurm_future.py`, `tests/test_launcher_remote.py` -- `tests/test_solution_variables.py` -- `tests/test_solvermode/` -- `tests/test_tui_api.py` -- `tests/test_public_api.py` -- `tests/test_settings_api.py` +- Expressions, variables, and utility APIs + - package: `src/ansys/fluent/core/expressions`, `src/ansys/fluent/core/rpvars.py`, `src/ansys/fluent/core/utils` + - entry: expression helpers, RP vars, utility wrappers + - tests: `tests/test_rp_vars.py`, `tests/test_lispy.py`, `tests/test_pyconsole.py`, `tests/test_type_stub.py` -Confidence: +- REST and UI helpers + - package: `src/ansys/fluent/core/rest`, `src/ansys/fluent/core/ui` + - entry: REST client and UI integrations + - tests: `tests/test_rest.py`, `tests/test_pyconsole.py`, relevant UI or web tests if present -- High for the public solver entry points and generated settings surfaces. -- Some exact internal boundaries may be generated and version-bound; this should be treated as generation-managed code unless the repo explicitly says otherwise. +## 4. High-value architectural rules -### 5.4 Fields, reductions, and solution variables +- The runtime package and session layer are the primary user-facing entry points. +- Generated code is authoritative for many schema-driven APIs; do not hand-edit it lightly. +- Field-data, reduction, settings, and datamodel access are higher-value feature areas than TUI-only command wrappers. +- For any version-specific path, prefer the generated or compatibility-aware implementation and confirm with the closest tests. +- If a feature is unclear, ask the user before assuming the route or test target. -Primary responsibility: +## 5. Validation strategy -- field-data access and reduction operations -- solution-variable metadata and data retrieval -- Fluent field and solution data workflows +Prefer the closest relevant test target before escalating: -Key entry points: - -- `src/ansys/fluent/core/fields/__init__.py` -- `FieldData`, `FieldDataBatch`, `Reduction`, `SolutionVariableData`, and `SolutionVariableInfo` -- lower-level services in `src/ansys/fluent/core/services` and gRPC field-data service modules - -Likely validation targets: - -- `tests/test_field_data.py` -- `tests/test_solution_variables.py` -- `tests/test_physical_quantities.py` - -Confidence: - -- High. This is a well-defined feature cluster with clear public entry points and direct test coverage. - -### 5.5 Settings and datamodel surfaces - -Primary responsibility: - -- Fluent settings access -- datamodel object navigation -- settings readers and schema-backed behaviors - -Key entry points: - -- session-level settings objects exposed from the runtime session -- generated settings modules under `src/ansys/fluent/core/generated` -- settings readers and model wrappers under the core runtime package - -Likely validation targets: - -- `tests/test_settings_api.py` -- `tests/test_settings_reader.py` -- `tests/test_datamodel_api.py` -- `tests/test_datamodel_service.py` -- `tests/test_builtin_settings.py` - -Confidence: - -- High for test coverage and public API surface. -- Very high generation dependence: if a bug is schema-driven, the generated layer should be treated as the source of truth before modifying runtime wrappers. - -### 5.6 File transfer and file-session workflows - -Primary responsibility: - -- file session access -- file transfer service behavior -- case/data reader workflows -- file-backed Fluent workflows - -Key entry points: - -- `src/ansys/fluent/core/session/file.py` -- `src/ansys/fluent/core/file_transfer_service.py` -- `src/ansys/fluent/core/file_reader` and related reader modules - -Likely validation targets: - -- `tests/test_file_session.py` -- `tests/test_file_transfer_service.py` -- `tests/test_datareader.py` -- `tests/test_casereader.py` - -Confidence: - -- High for the public file-related API surface. -- Some lower-level file-transfer behavior may depend on environment and Fluent runtime setup, so these are not always the cheapest validation targets. - -### 5.7 Public API and compatibility surface - -Primary responsibility: - -- package-level exports -- deprecations and compatibility shims -- high-level user-facing API stability - -Key entry points: - -- `src/ansys/fluent/core/__init__.py` -- compatibility and deprecation layers within the core package - -Likely validation targets: - -- `tests/test_public_api.py` -- `tests/test_deprecate.py` -- `tests/test_flobject.py` - -Confidence: - -- High for visible API/compatibility behaviors. - -## 6. How to choose the right validation path - -When a patch is in doubt, prefer this order: - -1. import/syntax check -2. nearest unit-level or API-level test -3. nearest feature test cluster -4. broader Fluent-session or integration tests only if required by the feature +1. import / syntax check +2. nearest feature test file +3. nearest subsystem suite +4. broader integration or Fluent-session tests only when required Examples: -- change in launch/session lifecycle → start with `test_launcher.py` or `test_fluent_session.py` -- change in meshing flow → use `test_meshing_workflow.py` and related meshing tests -- change in fields or solution variables → use `test_field_data.py` and `test_solution_variables.py` -- change in settings/datamodel behavior → use `test_settings_api.py` and `test_datamodel_api.py` -- change in file transfer or file reading → use the file-session and reader tests - -## 7. Agent-specific heuristics - -- If a change looks schema-driven, inspect the generated layer before editing runtime code. -- If a change affects public APIs, check tests and docs together. -- If a bug is in Fluent integration behavior, validate against the likely session/launcher and settings/datamodel path. -- If there is uncertainty about generated vs hand-authored code, search for generated markers before editing. -- When a mapping is unclear due to version-specific behavior, do not assume a single implementation; prefer the generated or compatibility-aware path and confirm with the nearest repo tests. - -## 8. Cost-aware usage guidance - -To reduce token use and improve answer quality: - -- read the local runtime and settings/datamodel entrypoints first -- search for the feature name before broad file scanning -- avoid reading the full generated tree unless the behavior is explicitly generated -- prefer the specific test file closest to the changed behavior -- treat large Fluent-session tests as escalation points, not default validation paths +- reduction bug: start at `src/ansys/fluent/core/fields/reduction.py` and `tests/test_reduction.py` +- file transfer bug: start at `src/ansys/fluent/core/file_transfer_service.py` and `tests/test_file_transfer_service.py` +- launch/session issue: start at `src/ansys/fluent/core/launcher` and `tests/test_launcher.py` +- settings/datamodel bug: start at the generated settings surface and `tests/test_settings_api.py` / `tests/test_datamodel_api.py` +- search bug: start at `src/ansys/fluent/core/search.py` and `tests/test_search.py` -This document is a map, not a manual. It should orient the agent and keep the work focused, not replace targeted investigation. +This map is intentionally compact but broad enough to route an agent quickly across the main PyFluent subsystems without scanning the whole repo. diff --git a/devel/agents/testing.md b/devel/agents/testing.md index d797d89ccb68..d6fef6b8efc0 100644 --- a/devel/agents/testing.md +++ b/devel/agents/testing.md @@ -37,12 +37,21 @@ The `tests` tree covers: Use this as a quick routing guide before choosing a test target: -- Launch and session lifecycle: `test_launcher.py`, `test_launcher_remote.py`, `test_fluent_session.py`, `test_session.py` -- Settings and datamodel API: `test_settings_api.py`, `test_settings_reader.py`, `test_datamodel_api.py`, `test_datamodel_service.py` -- Field data and solution variables: `test_field_data.py`, `test_solution_variables.py`, `test_physical_quantities.py` +- Launch and session lifecycle: `test_launcher.py`, `test_launcher_remote.py`, `test_fluent_session.py`, `test_session.py`, `test_pre_post_session.py` - Meshing workflows: `test_meshing_workflow.py`, `test_new_meshing_workflow.py`, `test_meshing_utilities.py`, `test_pure_mesh_vs_mesh_workflow.py`, `test_server_meshing_workflow.py` +- Solver and solver-mode behavior: `test_solution_variables.py`, `test_solvermode`, `test_tui_api.py`, `test_public_api.py` +- Fields and reduction: `test_field_data.py`, `test_reduction.py`, `test_solution_variables.py`, `test_physical_quantities.py` +- Settings and datamodel API: `test_settings_api.py`, `test_settings_reader.py`, `test_datamodel_api.py`, `test_datamodel_service.py`, `test_builtin_settings.py` - File and transfer behavior: `test_file_session.py`, `test_file_transfer_service.py`, `test_datareader.py`, `test_casereader.py` -- API and object surfaces: `test_flobject.py`, `test_tui_api.py`, `test_rp_vars.py`, `test_public_api.py` +- Search and API browsing: `test_search.py` +- API and object surfaces: `test_flobject.py`, `test_rp_vars.py`, `test_public_api.py` + +Concrete examples: + +- Reduction work first checks `src/ansys/fluent/core/fields/reduction.py` and then `tests/test_reduction.py`. +- Field-data work first checks `src/ansys/fluent/core/fields/live_field_data.py` and then `tests/test_field_data.py`. +- Search work first checks `src/ansys/fluent/core/search.py` and then `tests/test_search.py`. +- File transfer work first checks `src/ansys/fluent/core/file_transfer_service.py` and then `tests/test_file_transfer_service.py`. This is not exhaustive, but it gives a stable map from feature area to the most likely test cluster. From 52c4dc6802a4a548aa3d8cfd9bc5d48c70469b8e Mon Sep 17 00:00:00 2001 From: Prithwish Mukherjee Date: Thu, 24 Sep 2026 15:24:59 +0530 Subject: [PATCH 3/7] Update architecture. --- devel/agents/architecture.md | 164 ++++++++++++++++++++++------------- 1 file changed, 103 insertions(+), 61 deletions(-) diff --git a/devel/agents/architecture.md b/devel/agents/architecture.md index 6925b12bc484..ba455bf3ef4c 100644 --- a/devel/agents/architecture.md +++ b/devel/agents/architecture.md @@ -36,67 +36,109 @@ PyFluent exposes a Pythonic API on top of Ansys Fluent. The major layers are: ## 3. Feature-to-entry-point map -Use this as the first-stop lookup before reading code. - -- Launch and session lifecycle - - package: `src/ansys/fluent/core/launcher`, `src/ansys/fluent/core/session` - - entry: `pyfluent.launch_fluent()` - - tests: `tests/test_launcher.py`, `tests/test_launcher_remote.py`, `tests/test_fluent_session.py`, `tests/test_session.py`, `tests/test_pre_post_session.py` - -- Meshing - - package: `src/ansys/fluent/core/meshing`, `src/ansys/fluent/core/session/meshing.py` - - entry: `pyfluent.launch_fluent(mode="meshing")`, `Meshing`, `PureMeshing` - - tests: `tests/test_meshing_workflow.py`, `tests/test_new_meshing_workflow.py`, `tests/test_meshing_utilities.py`, `tests/test_pure_mesh_vs_mesh_workflow.py`, `tests/test_server_meshing_workflow.py` - -- Solver and solver variants - - package: `src/ansys/fluent/core/solver`, `src/ansys/fluent/core/session/solver.py` - - entry: `pyfluent.launch_fluent(mode="solver")`, `Solver`, `SolverAero`, `SolverIcing`, `PrePost` - - tests: `tests/test_solution_variables.py`, `tests/test_solvermode`, `tests/test_tui_api.py`, `tests/test_public_api.py`, `tests/test_settings_api.py` - -- Fields and reduction - - package: `src/ansys/fluent/core/fields` - - entry: `ansys.fluent.core.fields.FieldData`, `FieldDataBatch`, `Reduction`, `SolutionVariableData`, `SolutionVariableInfo` - - tests: `tests/test_field_data.py`, `tests/test_reduction.py`, `tests/test_solution_variables.py`, `tests/test_physical_quantities.py` - -- Settings and datamodel - - package: `src/ansys/fluent/core/services/object_model.py`, generated settings under `src/ansys/fluent/core/generated` - - entry: runtime session settings object tree and datamodel interfaces - - tests: `tests/test_settings_api.py`, `tests/test_settings_reader.py`, `tests/test_datamodel_api.py`, `tests/test_datamodel_service.py`, `tests/test_builtin_settings.py` - -- File transfer and file sessions - - package: `src/ansys/fluent/core/file_transfer_service.py`, `src/ansys/fluent/core/session/file.py`, `src/ansys/fluent/core/file_reader` - - entry: `FileSession`, file-transfer strategies and case/data readers - - tests: `tests/test_file_session.py`, `tests/test_file_transfer_service.py`, `tests/test_datareader.py`, `tests/test_casereader.py` - -- Search and API lookup - - package: `src/ansys/fluent/core/search.py` - - entry: `search(...)` - - tests: `tests/test_search.py` - -- Workflow and parametric study - - package: `src/ansys/fluent/core/workflow.py`, `src/ansys/fluent/core/local_parametric_study.py` - - entry: workflow objects and parametric study helpers - - tests: `tests/test_batch_ops.py`, `tests/test_scheduler.py`, `tests/test_slurm_future.py`, `tests/test_systemcoupling.py`, `tests/test_parametric` if present in the repo - -- Streaming, event, and service plumbing - - package: `src/ansys/fluent/core/services/streaming_services`, `src/ansys/fluent/core/services` - - entry: streaming services, events, monitor and transcript integrations - - tests: `tests/test_events_manager.py`, `tests/test_streaming_services.py` - -- Batch operations and remote execution - - package: `src/ansys/fluent/core/services/batch_ops.py`, `src/ansys/fluent/core/scheduler`, `src/ansys/fluent/core/docker` - - entry: batch operations and remote/scheduler launch flows - - tests: `tests/test_batch_ops.py`, `tests/test_scheduler.py`, `tests/test_slurm_future.py`, `tests/test_launcher_remote.py` - -- Expressions, variables, and utility APIs - - package: `src/ansys/fluent/core/expressions`, `src/ansys/fluent/core/rpvars.py`, `src/ansys/fluent/core/utils` - - entry: expression helpers, RP vars, utility wrappers - - tests: `tests/test_rp_vars.py`, `tests/test_lispy.py`, `tests/test_pyconsole.py`, `tests/test_type_stub.py` - -- REST and UI helpers - - package: `src/ansys/fluent/core/rest`, `src/ansys/fluent/core/ui` - - entry: REST client and UI integrations - - tests: `tests/test_rest.py`, `tests/test_pyconsole.py`, relevant UI or web tests if present +Use this as the first-stop lookup before reading code. Each section follows the same repo-aligned template: + +- module path +- public entry point +- feature intent +- tests to run +- generated/version-specific notes + +### 3.1 Launch and session lifecycle + +- module path: `src/ansys/fluent/core/launcher`, `src/ansys/fluent/core/session`, `src/ansys/fluent/core/__init__.py` +- public entry point: `pyfluent.launch_fluent()`, session classes such as `Solver`, `Meshing`, `PureMeshing`, `FileSession`, and `PrePost` +- feature intent: create Fluent sessions, switch runtime modes, and manage lifecycle, health checks, and command routing +- tests to run: `tests/test_launcher.py`, `tests/test_launcher_remote.py`, `tests/test_fluent_session.py`, `tests/test_session.py`, `tests/test_pre_post_session.py` +- generated/version-specific notes: session behavior is runtime-sensitive and often depends on Fluent version and launch mode; prefer the session and launcher entry points before reading the generated tree + +### 3.2 Meshing workflows + +- module path: `src/ansys/fluent/core/meshing`, `src/ansys/fluent/core/session/meshing.py` +- public entry point: `pyfluent.launch_fluent(mode="meshing")`, `Meshing`, `PureMeshing` +- feature intent: meshing mode workflows, meshing-specific operations, and transitions between mesh and solver workflows +- tests to run: `tests/test_meshing_workflow.py`, `tests/test_new_meshing_workflow.py`, `tests/test_meshing_utilities.py`, `tests/test_pure_mesh_vs_mesh_workflow.py`, `tests/test_server_meshing_workflow.py` +- generated/version-specific notes: workflow implementation may vary by Fluent packaging and mesh mode compatibility; validate against the nearest meshing tests before assuming a single path + +### 3.3 Solver and solver variants + +- module path: `src/ansys/fluent/core/solver`, `src/ansys/fluent/core/session/solver.py`, `src/ansys/fluent/core/generated` +- public entry point: `pyfluent.launch_fluent(mode="solver")`, `Solver`, `SolverAero`, `SolverIcing`, `PrePost` +- feature intent: solve-mode sessions, solver-specific APIs, and generated object-model surfaces +- tests to run: `tests/test_solution_variables.py`, `tests/test_solvermode`, `tests/test_tui_api.py`, `tests/test_public_api.py`, `tests/test_settings_api.py` +- generated/version-specific notes: many solver and settings entry points are generation-managed; treat the generated layer as authoritative unless the task explicitly requires a runtime wrapper change + +### 3.4 Field data, reduction, and solution variables + +- module path: `src/ansys/fluent/core/fields`, `src/ansys/fluent/core/services` +- public entry point: `ansys.fluent.core.fields.FieldData`, `FieldDataBatch`, `Reduction`, `SolutionVariableData`, `SolutionVariableInfo` +- feature intent: access live field data, compute reductions, and inspect solution-variable metadata and values +- tests to run: `tests/test_field_data.py`, `tests/test_reduction.py`, `tests/test_solution_variables.py`, `tests/test_physical_quantities.py` +- generated/version-specific notes: field and solution-variable paths are usually part of the runtime API surface rather than generated model wrappers, but they can still depend on service behavior and Fluent schema versioning + +### 3.5 Settings and datamodel + +- module path: `src/ansys/fluent/core/generated`, `src/ansys/fluent/core/services/object_model.py`, session settings surfaces +- public entry point: runtime session settings object tree and datamodel interfaces +- feature intent: expose Fluent settings and object-model navigation in a Pythonic, structured form +- tests to run: `tests/test_settings_api.py`, `tests/test_settings_reader.py`, `tests/test_datamodel_api.py`, `tests/test_datamodel_service.py`, `tests/test_builtin_settings.py` +- generated/version-specific notes: this is a core generation-managed area; if the behavior is schema-driven, inspect the generated code before editing runtime wrappers + +### 3.6 File transfer and file sessions + +- module path: `src/ansys/fluent/core/file_transfer_service.py`, `src/ansys/fluent/core/session/file.py`, `src/ansys/fluent/core/file_reader` +- public entry point: `FileSession`, file-transfer strategies, and case/data readers +- feature intent: read and transfer Fluent case/data files and operate against file-backed session workflows +- tests to run: `tests/test_file_session.py`, `tests/test_file_transfer_service.py`, `tests/test_datareader.py`, `tests/test_casereader.py` +- generated/version-specific notes: file behavior is often environment-sensitive and may depend on Fluent runtime setup; treat reader/service tests as the primary validation target before broader integration tests + +### 3.7 Search and API lookup + +- module path: `src/ansys/fluent/core/search.py` +- public entry point: `search(...)` +- feature intent: discover Fluent objects and APIs by name or object path across the exposed model surface +- tests to run: `tests/test_search.py` +- generated/version-specific notes: search is usually layer-aware and object-model dependent, so it should be validated against the nearest public lookup tests when schema or object names change + +### 3.8 Workflow and parametric study + +- module path: `src/ansys/fluent/core/workflow.py`, `src/ansys/fluent/core/workflow_old.py`, `src/ansys/fluent/core/local_parametric_study.py` +- public entry point: workflow objects and parametric-study helpers +- feature intent: hold automation workflows, batch operations, and parametric study orchestration over Fluent sessions +- tests to run: `tests/test_batch_ops.py`, `tests/test_scheduler.py`, `tests/test_slurm_future.py`, `tests/test_systemcoupling.py`, `tests/test_parametric` if present in the repo +- generated/version-specific notes: these workflows often mix runtime orchestration and generated API behavior; prefer the specific workflow test cluster rather than broad session tests + +### 3.9 Streaming, events, and service plumbing + +- module path: `src/ansys/fluent/core/services`, `src/ansys/fluent/core/services/streaming_services` +- public entry point: streaming services, event managers, monitor hooks, and transcript integrations +- feature intent: provide asynchronous service and event plumbing for Fluent runtime interactions +- tests to run: `tests/test_events_manager.py`, `tests/test_streaming_services.py` +- generated/version-specific notes: event and streaming behavior is usually service-layer specific and should be validated near the service/monitor path rather than broad session tests + +### 3.10 Batch operations and remote execution + +- module path: `src/ansys/fluent/core/services/batch_ops.py`, `src/ansys/fluent/core/scheduler`, `src/ansys/fluent/core/docker` +- public entry point: batch operation helpers and remote scheduler launch flows +- feature intent: orchestrate remote or queued Fluent execution patterns for larger automation work +- tests to run: `tests/test_batch_ops.py`, `tests/test_scheduler.py`, `tests/test_slurm_future.py`, `tests/test_launcher_remote.py` +- generated/version-specific notes: remote execution can change significantly by environment and Fluent packaging; start with the scheduler and batch tests before any broad integration path + +### 3.11 Expressions, variables, and utility APIs + +- module path: `src/ansys/fluent/core/expressions`, `src/ansys/fluent/core/rpvars.py`, `src/ansys/fluent/core/utils` +- public entry point: expression helpers, RP variables, and general utility wrappers +- feature intent: provide expression evaluation, variable access, and generic helper logic around Fluent operations +- tests to run: `tests/test_rp_vars.py`, `tests/test_lispy.py`, `tests/test_pyconsole.py`, `tests/test_type_stub.py` +- generated/version-specific notes: this area is often runtime helper-driven rather than schema-driven, but some behavior may still reflect Fluent version-specific naming or object semantics + +### 3.12 REST and UI helpers + +- module path: `src/ansys/fluent/core/rest`, `src/ansys/fluent/core/ui` +- public entry point: REST client interfaces and UI integration helpers +- feature intent: support REST and UI-oriented interactions around Fluent sessions and tooling +- tests to run: `tests/test_rest.py`, `tests/test_pyconsole.py`, and any UI/web tests present in the repository +- generated/version-specific notes: REST/UI integrations are usually not generation-managed; they are more likely to be compatibility wrappers and environment-dependent adapters ## 4. High-value architectural rules From 90633d11024d9e52eb80c394dcc8af9fc28e8992 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Thu, 24 Sep 2026 12:42:26 +0000 Subject: [PATCH 4/7] chore: adding changelog file 5413.added.md [dependabot-skip] --- doc/changelog.d/5413.added.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/5413.added.md diff --git a/doc/changelog.d/5413.added.md b/doc/changelog.d/5413.added.md new file mode 100644 index 000000000000..1a449738e45d --- /dev/null +++ b/doc/changelog.d/5413.added.md @@ -0,0 +1 @@ +Include agents md From 75b02229123cd16a9fe8bd411fe58700f32e7e77 Mon Sep 17 00:00:00 2001 From: Prithwish Mukherjee Date: Fri, 2 Oct 2026 21:21:17 +0530 Subject: [PATCH 5/7] Updates. --- .github/copilot-instructions.md | 22 +-- AGENTS.md | 19 ++- devel/agents/architecture.md | 276 ++++++++++++++------------------ devel/agents/testing.md | 90 +++++------ devel/agents/workflows.md | 41 +++-- 5 files changed, 196 insertions(+), 252 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 2f33c120c393..f3d8958f6628 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,23 +1,5 @@ # GitHub Copilot instructions for PyFluent -This file is intentionally minimal. The canonical project guidance lives in @AGENTS.md at the repository root. Use that file as the single source of truth for setup, repo map, commands, and default operating rules. +Read @AGENTS.md first and follow it as the canonical setup, repo map, commands, and operating rules. `src/ansys/fluent/core` is the runtime package; generated modules are generation-managed unless the task requires otherwise. -## Required behavior - -- Read @AGENTS.md first for project orientation. -- Follow the repo rules in @AGENTS.md before expanding to deeper docs. -- Keep this file short; do not duplicate the root guidance. - -## Repo-specific override - -- Treat `src/ansys/fluent/core` as the main runtime package. -- Treat generated modules as schema-driven or generation-managed code unless a task explicitly requires otherwise. - -## Documentation hierarchy - -- @AGENTS.md — canonical startup and repo guidance -- @devel/agents/architecture.md — subsystem and architecture map -- @devel/agents/testing.md — validation strategy -- @devel/agents/workflows.md — contribution workflow - -This file should stay brief and point to the canonical guidance rather than repeating it. +Load only relevant sections: @devel/agents/architecture.md (source owners), @devel/agents/testing.md (tests/requirements), @devel/agents/workflows.md (commands/maintenance). Keep this file a short pointer; do not duplicate those maps or rules. diff --git a/AGENTS.md b/AGENTS.md index 495cd3542a8b..0eaa5bece806 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,12 @@ pre-commit run --all-files ## Repo map - `src/ansys/fluent/core` — runtime package +- `src/ansys/fluent/core/execution` — launchers, base-session context, file sessions, containers, schedulers +- `src/ansys/fluent/core/connectivity` — Fluent connections and file/data transfer +- `src/ansys/fluent/core/meshing` — meshing sessions and pre-set meshing workflows +- `src/ansys/fluent/core/solver` — solver sessions and solver APIs, including settings objects +- `src/ansys/fluent/core/fields` / `services` — field APIs and backend transports +- `src/ansys/fluent/core/diagnostics` — search, logging, journaling, exceptions - `src/ansys/fluent/core/generated` — generated API code - `codegen` — generation workflow - `tests` — behavior and regression tests @@ -39,19 +45,22 @@ pre-commit run --all-files 1. Start with one targeted search and the smallest relevant reads. 2. Prefer existing tests and project conventions over guessing. -3. Keep patches narrow and fix one root cause. +3. Diagnose the root cause and fix it in the owning abstraction; avoid symptom patches or workarounds. Keep changes narrow and unrelated behavior untouched. 4. Do not hand-edit generated API files unless required. 5. Validate with the smallest relevant test target. 6. Prefer cheap validation first: import checks, syntax checks, and nearby non-Fluent tests. 7. Avoid large integration or active-Fluent-session tests unless the change truly requires them. 8. If imports, package boundaries, or public APIs are affected, check import paths before escalating. 9. If the subsystem, feature mapping, or test target is unclear, ask the user instead of guessing. +10. Use current implementation paths, not legacy import aliases, to locate owners; check public compatibility aliases in `src/ansys/fluent/core/__init__.py` when imports change. +11. Follow standard software design principles: separation of concerns, cohesive responsibilities, explicit contracts, and minimal coupling. Prefer existing patterns, simple solutions, and justified abstractions over duplication or speculative complexity. +12. Preserve user changes and existing instruction intent; confirm before removing instructions. When new concepts, anomalies, or stale guidance suggest an improvement, explain the evidence and proposed update, ask the user, and modify `AGENTS.md` or the relevant guide only after approval. Keep updates concise and verified; remove duplication, not unique facts, constraints, or safety rules. ## Deeper guidance -- `devel/agents/architecture.md` — subsystem map -- `devel/agents/testing.md` — validation strategy -- `devel/agents/workflows.md` — contribution workflow +- `devel/agents/architecture.md` — source owners, feature entry points, runtime relationships +- `devel/agents/testing.md` — test map, cheap targets, dependencies and skip rules +- `devel/agents/workflows.md` — contribution, generation, CI/docs commands and maintenance - `.github/copilot-instructions.md` — short repo-specific pointer -Use these only when the task touches Fluent lifecycle, meshing/solver APIs, settings/datamodel generation, packaging, or CI behavior. +Load only the relevant section when routing or validation is unclear, or the task touches lifecycle, meshing/solver APIs, generation, packaging, or CI. Do not preload all guides or duplicate their maps here. diff --git a/devel/agents/architecture.md b/devel/agents/architecture.md index ba455bf3ef4c..94718eb16b6a 100644 --- a/devel/agents/architecture.md +++ b/devel/agents/architecture.md @@ -1,168 +1,124 @@ -# Architecture map for AI agents - -This document is intentionally small but repo-specific. It gives agents the fastest path to the right feature area and the most relevant validation target. - -## 1. Product shape - -PyFluent exposes a Pythonic API on top of Ansys Fluent. The major layers are: - -1. Fluent launch and session management -2. Meshing and solver sessions -3. Settings and datamodel surfaces -4. Generated API layer -5. Field data, reduction, and solution-variable workflows -6. File transfer, file sessions, and reader workflows -7. Search, workflows, scheduling, remote execution, and API utilities - -## 2. Core package map - -- `src/ansys/fluent/core/__init__.py` — top-level package exports and public entry points -- `src/ansys/fluent/core/launcher` — launch orchestration and mode selection -- `src/ansys/fluent/core/session` — concrete session classes: solver, meshing, file, pre/post -- `src/ansys/fluent/core/meshing` — meshing workflows and workflow wrappers -- `src/ansys/fluent/core/solver` — solver API surface and generated settings entry points -- `src/ansys/fluent/core/fields` — field data, reduction, solution variables -- `src/ansys/fluent/core/services` — service interfaces and backend wrappers -- `src/ansys/fluent/core/file_transfer_service.py` — file transfer service -- `src/ansys/fluent/core/file_reader` — case/data file readers -- `src/ansys/fluent/core/search.py` — search API across object hierarchy -- `src/ansys/fluent/core/workflow.py`, `workflow_old.py` — workflow wrappers and compatibility paths -- `src/ansys/fluent/core/local_parametric_study.py` — parametric study support -- `src/ansys/fluent/core/scheduler` — scheduler integration -- `src/ansys/fluent/core/rest` and `src/ansys/fluent/core/ui` — REST / UI helpers -- `src/ansys/fluent/core/utils` — general utilities and setup helpers -- `src/ansys/fluent/core/generated` — generated API layer; treat as generation-managed unless a task explicitly requires otherwise -- `codegen` — generation scripts and schema-driven workflows - -## 3. Feature-to-entry-point map - -Use this as the first-stop lookup before reading code. Each section follows the same repo-aligned template: - -- module path -- public entry point -- feature intent -- tests to run -- generated/version-specific notes - -### 3.1 Launch and session lifecycle - -- module path: `src/ansys/fluent/core/launcher`, `src/ansys/fluent/core/session`, `src/ansys/fluent/core/__init__.py` -- public entry point: `pyfluent.launch_fluent()`, session classes such as `Solver`, `Meshing`, `PureMeshing`, `FileSession`, and `PrePost` -- feature intent: create Fluent sessions, switch runtime modes, and manage lifecycle, health checks, and command routing -- tests to run: `tests/test_launcher.py`, `tests/test_launcher_remote.py`, `tests/test_fluent_session.py`, `tests/test_session.py`, `tests/test_pre_post_session.py` -- generated/version-specific notes: session behavior is runtime-sensitive and often depends on Fluent version and launch mode; prefer the session and launcher entry points before reading the generated tree - -### 3.2 Meshing workflows - -- module path: `src/ansys/fluent/core/meshing`, `src/ansys/fluent/core/session/meshing.py` -- public entry point: `pyfluent.launch_fluent(mode="meshing")`, `Meshing`, `PureMeshing` -- feature intent: meshing mode workflows, meshing-specific operations, and transitions between mesh and solver workflows -- tests to run: `tests/test_meshing_workflow.py`, `tests/test_new_meshing_workflow.py`, `tests/test_meshing_utilities.py`, `tests/test_pure_mesh_vs_mesh_workflow.py`, `tests/test_server_meshing_workflow.py` -- generated/version-specific notes: workflow implementation may vary by Fluent packaging and mesh mode compatibility; validate against the nearest meshing tests before assuming a single path - -### 3.3 Solver and solver variants - -- module path: `src/ansys/fluent/core/solver`, `src/ansys/fluent/core/session/solver.py`, `src/ansys/fluent/core/generated` -- public entry point: `pyfluent.launch_fluent(mode="solver")`, `Solver`, `SolverAero`, `SolverIcing`, `PrePost` -- feature intent: solve-mode sessions, solver-specific APIs, and generated object-model surfaces -- tests to run: `tests/test_solution_variables.py`, `tests/test_solvermode`, `tests/test_tui_api.py`, `tests/test_public_api.py`, `tests/test_settings_api.py` -- generated/version-specific notes: many solver and settings entry points are generation-managed; treat the generated layer as authoritative unless the task explicitly requires a runtime wrapper change - -### 3.4 Field data, reduction, and solution variables - -- module path: `src/ansys/fluent/core/fields`, `src/ansys/fluent/core/services` -- public entry point: `ansys.fluent.core.fields.FieldData`, `FieldDataBatch`, `Reduction`, `SolutionVariableData`, `SolutionVariableInfo` -- feature intent: access live field data, compute reductions, and inspect solution-variable metadata and values -- tests to run: `tests/test_field_data.py`, `tests/test_reduction.py`, `tests/test_solution_variables.py`, `tests/test_physical_quantities.py` -- generated/version-specific notes: field and solution-variable paths are usually part of the runtime API surface rather than generated model wrappers, but they can still depend on service behavior and Fluent schema versioning - -### 3.5 Settings and datamodel - -- module path: `src/ansys/fluent/core/generated`, `src/ansys/fluent/core/services/object_model.py`, session settings surfaces -- public entry point: runtime session settings object tree and datamodel interfaces -- feature intent: expose Fluent settings and object-model navigation in a Pythonic, structured form -- tests to run: `tests/test_settings_api.py`, `tests/test_settings_reader.py`, `tests/test_datamodel_api.py`, `tests/test_datamodel_service.py`, `tests/test_builtin_settings.py` -- generated/version-specific notes: this is a core generation-managed area; if the behavior is schema-driven, inspect the generated code before editing runtime wrappers - -### 3.6 File transfer and file sessions - -- module path: `src/ansys/fluent/core/file_transfer_service.py`, `src/ansys/fluent/core/session/file.py`, `src/ansys/fluent/core/file_reader` -- public entry point: `FileSession`, file-transfer strategies, and case/data readers -- feature intent: read and transfer Fluent case/data files and operate against file-backed session workflows -- tests to run: `tests/test_file_session.py`, `tests/test_file_transfer_service.py`, `tests/test_datareader.py`, `tests/test_casereader.py` -- generated/version-specific notes: file behavior is often environment-sensitive and may depend on Fluent runtime setup; treat reader/service tests as the primary validation target before broader integration tests - -### 3.7 Search and API lookup - -- module path: `src/ansys/fluent/core/search.py` -- public entry point: `search(...)` -- feature intent: discover Fluent objects and APIs by name or object path across the exposed model surface -- tests to run: `tests/test_search.py` -- generated/version-specific notes: search is usually layer-aware and object-model dependent, so it should be validated against the nearest public lookup tests when schema or object names change - -### 3.8 Workflow and parametric study - -- module path: `src/ansys/fluent/core/workflow.py`, `src/ansys/fluent/core/workflow_old.py`, `src/ansys/fluent/core/local_parametric_study.py` -- public entry point: workflow objects and parametric-study helpers -- feature intent: hold automation workflows, batch operations, and parametric study orchestration over Fluent sessions -- tests to run: `tests/test_batch_ops.py`, `tests/test_scheduler.py`, `tests/test_slurm_future.py`, `tests/test_systemcoupling.py`, `tests/test_parametric` if present in the repo -- generated/version-specific notes: these workflows often mix runtime orchestration and generated API behavior; prefer the specific workflow test cluster rather than broad session tests - -### 3.9 Streaming, events, and service plumbing - -- module path: `src/ansys/fluent/core/services`, `src/ansys/fluent/core/services/streaming_services` -- public entry point: streaming services, event managers, monitor hooks, and transcript integrations -- feature intent: provide asynchronous service and event plumbing for Fluent runtime interactions -- tests to run: `tests/test_events_manager.py`, `tests/test_streaming_services.py` -- generated/version-specific notes: event and streaming behavior is usually service-layer specific and should be validated near the service/monitor path rather than broad session tests - -### 3.10 Batch operations and remote execution - -- module path: `src/ansys/fluent/core/services/batch_ops.py`, `src/ansys/fluent/core/scheduler`, `src/ansys/fluent/core/docker` -- public entry point: batch operation helpers and remote scheduler launch flows -- feature intent: orchestrate remote or queued Fluent execution patterns for larger automation work -- tests to run: `tests/test_batch_ops.py`, `tests/test_scheduler.py`, `tests/test_slurm_future.py`, `tests/test_launcher_remote.py` -- generated/version-specific notes: remote execution can change significantly by environment and Fluent packaging; start with the scheduler and batch tests before any broad integration path - -### 3.11 Expressions, variables, and utility APIs - -- module path: `src/ansys/fluent/core/expressions`, `src/ansys/fluent/core/rpvars.py`, `src/ansys/fluent/core/utils` -- public entry point: expression helpers, RP variables, and general utility wrappers -- feature intent: provide expression evaluation, variable access, and generic helper logic around Fluent operations -- tests to run: `tests/test_rp_vars.py`, `tests/test_lispy.py`, `tests/test_pyconsole.py`, `tests/test_type_stub.py` -- generated/version-specific notes: this area is often runtime helper-driven rather than schema-driven, but some behavior may still reflect Fluent version-specific naming or object semantics - -### 3.12 REST and UI helpers - -- module path: `src/ansys/fluent/core/rest`, `src/ansys/fluent/core/ui` -- public entry point: REST client interfaces and UI integration helpers -- feature intent: support REST and UI-oriented interactions around Fluent sessions and tooling -- tests to run: `tests/test_rest.py`, `tests/test_pyconsole.py`, and any UI/web tests present in the repository -- generated/version-specific notes: REST/UI integrations are usually not generation-managed; they are more likely to be compatibility wrappers and environment-dependent adapters - -## 4. High-value architectural rules +# Architecture map + +Follow `AGENTS.md`. Source paths below are relative to `src/ansys/fluent/core`; test targets and execution requirements live in `devel/agents/testing.md`. + +## Project orchestration + +Read the diagrams for relationships, then use the owner table for exact edit locations. Arrows show conceptual control/data flow, not class inheritance or every import; dashed arrows show supporting inputs. Fluent itself is an external process, not Python code in this repository. + +### Runtime paths + +```mermaid +flowchart TB + user["User scripts / examples / integrations"] --> public["Public exports: ansys.fluent.core"] + public --> launch["execution/launcher: launch or connect"] + platforms["Standalone / containers / PIM / Slurm"] --> launch + resources["execution/docker + scheduler: containers / machine allocation"] -.-> launch + launch --> connection["connectivity: FluentConnection / channel / cleanup"] + launch --> sessions["execution/session: BaseSession / active context"] + connection --> factories["Version-aware gRPC and high-level service factories"] + factories --> sessions + sessions --> meshing["meshing/session: Meshing / PureMeshing"] + sessions --> solver["solver/session: Solver and variants"] + meshing --> workflows["Pre-set meshing workflows + shared workflow wrappers"] + meshing --> model["Datamodel / TUI wrappers + datamodel cache"] + workflows --> model + solver --> settings["solver/flobject: settings objects / built-ins"] + solver --> model + sessions --> fields["fields: field data / solver reductions and solution variables"] + sessions --> streaming["Events / monitors / transcript / data streaming"] + settings --> services["services: abstractions and high-level wrappers"] + model --> services + fields --> services + streaming --> services + services --> grpc["_grpc_services: backend implementations / protocol versions"] + proto["External ansys-api-fluent: generated protobuf / gRPC schemas"] -.-> grpc + grpc --> channel["gRPC channel managed by FluentConnection"] + channel --> fluent["External Fluent server"] + user --> http["REST client + independent HttpSolver"] + http --> restsettings["services/rest_settings + shared flobject settings runtime"] + restsettings --> transport["rest: client / HTTP transport"] + transport --> web["External Fluent web server: 27.1+"] + user --> offline["FileSession + file_reader: case/data-backed APIs"] + files["Case / data assets"] --> offline + transfer["connectivity: file/data transfer strategies"] -.-> sessions + transfer -.-> files +``` + +- Settings, datamodel and TUI are distinct surfaces; they share session/service infrastructure but have different wrappers and schemas. Fields use runtime APIs, not generated settings wrappers. +- Expression/naming helpers support variable access; RP/Scheme helpers use services. Parametric studies orchestrate sessions; system coupling integrates solver operations with external coupled workflows. +- UI integrates session web/Jupyter presentation. Configuration, diagnostics, utilities, shared types and example downloads support the runtime across layers; search reads the generated API index rather than being a transport. + +### Generation and repository tooling + +Paths in this diagram are repository-relative. Detailed commands and prerequisites remain in `devel/agents/workflows.md` rather than being duplicated here. + +```mermaid +flowchart LR + driver["codegen/allapigen.py: live generation driver"] --> live["Meshing + solver-icing sessions: static info / workflow tasks"] + live --> generators["src/ansys/fluent/core/codegen: schema generators"] + generators --> output["generated: versioned settings / datamodel / TUI / task stubs + shared built-ins / API index"] + output -.-> runtime["Runtime wrappers / built-in settings / search"] + output -.-> docs["doc: API RST generators + Sphinx sources / gallery"] + examples["examples: end-to-end user workflows"] --> runtime + examples --> docs + tests["tests: unit / live Fluent / version-mode / external integration"] --> runtime + tests --> generators + packaging["pyproject.toml + requirements: dependencies / extras / build and tool config"] -.-> runtime + packaging -.-> tests + ci[".github/workflows + .ci + Makefile: build / generate / test / docs / release lanes"] --> driver + ci --> tests + ci --> docs + ci --> packaging + guidance["AGENTS.md + devel/agents: routing / validation / operating rules"] -.-> work["Agent / contributor work"] + notes["devel: engineering notes / investigations"] -.-> work + work --> runtime + work --> generators + work --> tests +``` + +## Source owners and entry points + +| Feature / public surface | Source owner | +| --- | --- | +| Public exports, legacy aliases; configuration/environment defaults | `__init__.py`; `module_config.py` | +| `launch_fluent()`, `connect_to_fluent()`; standalone/container/PIM/Slurm | `execution/launcher/launcher.py`; `execution/launcher/standalone_launcher.py`, `execution/launcher/container_launcher.py`, `execution/launcher/pim_launcher.py`, `execution/launcher/slurm_launcher.py` | +| Base session, `using()`, file-backed `FileSession` | `execution/session/session.py`; `execution/session/file.py` | +| gRPC connection lifetime, health checks, cleanup; file/data transfer | `connectivity/fluent_connection.py`; `connectivity/file_transfer_service.py`, `connectivity/data_transfer.py` | +| `Meshing`, `PureMeshing`; pre-set workflows and solver transitions | `meshing/session`; `meshing/meshing_workflow.py`, `meshing/meshing_workflow_old.py`; shared `workflow.py`, `workflow_old.py` | +| `Solver`, `SolverAero`, `SolverIcing`, `SolverLite`, `PrePost`; solve-mode APIs | `solver/session`; settings runtime in `solver/flobject.py` | +| `solver.settings`; built-in settings exports from `ansys.fluent.core.solver` | `solver/flobject.py`, `solver/settings_builtin_bases.py`, `solver/settings_builtin_data.py`; `services/settings.py` | +| Meshing datamodel roots; `session.tui` | `services/object_model.py`, `_data_model_cache.py`; `services/text_interface.py` | +| `session.fields.field_data`, `.new_batch()`; solver fields: `.reduction`, `.solution_variable_data`, `.solution_variable_info` | `fields/field_data/live_field_data.py`; `fields/reduction/reduction.py`; `fields/solution_variables/solution_variables.py` | +| Service abstractions/wrappers; events, monitors, transcripts and datamodel/field streaming | `services`; `services/streaming_services`; gRPC implementations in `_grpc_services` | +| Case/data readers and file-backed fields | `file_reader`; `execution/session/file.py` | +| `search(...)`, logging, journaling, exceptions | `diagnostics`; search implementation `diagnostics/search.py`, API index generator `codegen/api_tree.py` | +| Parametric studies; coupled simulation | `local_parametric_study.py`; `system_coupling.py` | +| Batch service calls; separately, queued/remote execution | `services/batch_ops.py`; `execution/scheduler`, `execution/docker`, launchers above | +| Expression construction/evaluation, RP variables, Scheme, file S-expressions | `expressions`; `rpvars.py`; `services/scheme_interpreter.py`; `file_reader/lispy.py` | +| `rest.connect_to_webserver()`, `FluentRestClient`, `HttpSolver` | `rest/client.py`, `rest/transport.py`, `services/rest_settings.py`, `solver/session/http_solver.py` | +| Web/Jupyter UI; utilities/setup; example downloads/assets | `ui`; `utils`; `examples` | +| Generated settings/datamodel/TUI/built-ins/search index; generation implementation | `generated`; `codegen/settingsgen.py`, `codegen/datamodelgen.py`, `codegen/tuigen.py`, `codegen/builtin_settingsgen.py`, `codegen/api_tree.py` (repository-root `codegen/allapigen.py` is the live-Fluent driver) | +| Shared types/launcher arguments; descriptor naming for expressions/fields/solution variables | `_types.py`; `_variable_strategies` | +| Legacy standalone datamodel-server helper, not a normal session entry point | `_stand_alone_datamodel_client/_datamodel_client.py`; verify its old imports/dependencies before use | + +### Runtime contracts + +- `FluentMode` in `execution/launcher/launch_options.py` accepts `meshing`, `pure_meshing`, `solver` (default), `solver_icing`, `solver_aero`, `pre_post`. The first five route to their corresponding sessions; `pre_post` currently maps to `Solver`. Do not infer launch support from the existence of a session class. +- `BaseSession` and `using()` live in execution; mode-specific sessions live in meshing/solver. `FileSession` is file-backed, not a live solver subclass; `HttpSolver` is independent of `BaseSession` and gRPC infrastructure. +- Solver settings objects use `solver/flobject.py` over a settings service. `get_root()` builds classes from static info when `config.use_runtime_python_classes` is enabled or the generated settings file is missing; otherwise it loads version-specific generated classes. +- Generated output uses version directories under `generated`, plus shared `generated/solver` and `generated/api_tree` data. Versions present in a local checkout depend on generation/install state; do not assume every supported version is generated locally. +- Legacy names registered in `__init__.py` are compatibility aliases, not current source locations. Start from the implementation path and check exports separately. + +## Architectural rules - The runtime package and session layer are the primary user-facing entry points. - Generated code is authoritative for many schema-driven APIs; do not hand-edit it lightly. - Field-data, reduction, settings, and datamodel access are higher-value feature areas than TUI-only command wrappers. - For any version-specific path, prefer the generated or compatibility-aware implementation and confirm with the closest tests. - If a feature is unclear, ask the user before assuming the route or test target. +- Fix runtime navigation/behavior in its owning wrapper or service; change generation logic for schema-output defects rather than hand-editing generated output. -## 5. Validation strategy - -Prefer the closest relevant test target before escalating: - -1. import / syntax check -2. nearest feature test file -3. nearest subsystem suite -4. broader integration or Fluent-session tests only when required - -Examples: - -- reduction bug: start at `src/ansys/fluent/core/fields/reduction.py` and `tests/test_reduction.py` -- file transfer bug: start at `src/ansys/fluent/core/file_transfer_service.py` and `tests/test_file_transfer_service.py` -- launch/session issue: start at `src/ansys/fluent/core/launcher` and `tests/test_launcher.py` -- settings/datamodel bug: start at the generated settings surface and `tests/test_settings_api.py` / `tests/test_datamodel_api.py` -- search bug: start at `src/ansys/fluent/core/search.py` and `tests/test_search.py` +Session, workflow, service and schema behavior varies by Fluent version, mode, packaging and environment. Check the closest compatibility-aware implementation and test rather than assuming one path. -This map is intentionally compact but broad enough to route an agent quickly across the main PyFluent subsystems without scanning the whole repo. +File-backed APIs need no live server themselves; reader tests may need assets/downloads or Fluent. Search consumes generated API-index data and semantic search needs NLTK data. `HttpSolver` targets Fluent 27.1+; REST settings can use runtime classes without generated files. UI needs `ui` / `ui-jupyter` extras; Python-console tests are not UI-rendering coverage. diff --git a/devel/agents/testing.md b/devel/agents/testing.md index d6fef6b8efc0..4e13e92ad588 100644 --- a/devel/agents/testing.md +++ b/devel/agents/testing.md @@ -1,58 +1,58 @@ # Testing strategy -Use the smallest relevant test target that checks the changed behavior. +Follow `AGENTS.md`: validate imports/syntax, then the nearest behavior-scoped node/file, then subsystem/integration tests only as needed. Prefer real behavior over mock-only assertions; validate downstream contracts for generated/schema changes and add a focused public-API regression test. Never replace relevant validation with unrelated cheap tests. -## Canonical command +## Commands + +`python -m pytest tests` is the broad default, not the starting point for a narrow fix: ```bash -python -m pytest tests +python -m pytest tests/test_rest.py +python -m pytest tests/test_search.py::test_match_whole_word +python -m pytest tests/test_settings_api.py -k relevant_behavior --fluent-version=26.1 +python -m pytest tests/test_solvermode/test_models.py --solvermode --fluent-version=26.1 ``` -## Rules - -1. Start from the nearest test file or selection for the changed behavior. -2. Prefer real behavior validation over mock-only assertions. -3. If the change touches generated or schema-driven code, validate the downstream contract as well. -4. Do not default to a full suite for a narrow fix. -5. Prefer cheap validation first: import checks, syntax checks, and the closest non-Fluent tests. -6. Avoid large integration suites or tests requiring an active Fluent session unless the change genuinely requires them. -7. If the change affects imports, package boundaries, or public APIs, validate import paths and package exposure before escalating. -8. If a public API regression is fixed, add or update a focused test. -9. If the correct test target is unclear, ask the user instead of guessing or running broad suites. -10. Keep the first objective in mind: good answers with minimal token usage; use the cheapest validation that still checks the behavior. +Use the actual target Fluent version. `python -m pytest --collect-only ` checks imports/node IDs without ordinary fixture execution; it does not prove tests will run rather than skip. -## Repo context +## Requirements and skips -The `tests` tree covers: +The source of truth is `pyproject.toml` (`tool.pytest.ini_options`) and `tests/conftest.py`: -- runtime API behavior -- Fluent launch and session lifecycle -- settings/datamodel access -- field data and solution-variable workflows -- meshing and solver-mode behavior -- file transfer and session persistence -- regression and compatibility checks +- Discovery starts in `tests`; generated-on-demand `tests/fluent` and `tests/journals` are ignored. `--write-fluent-journals` regenerates output and clears the collected run; not routine validation. +- `nightly` tests skip without `--nightly`. This flag enables nightly tests in addition to ordinary tests. +- `tests/test_solvermode` runs only with `--solvermode`; that flag also skips tests outside that directory. `tests/test_meshingmode` has no corresponding mode flag. +- `fluent_version(spec)` checks `--fluent-version` if supplied. `latest` means the current release in ordinary runs and release-or-newer in nightly/solvermode runs; `dev` means the current development version. Omitting the version option does not automatically filter unsupported tests. +- `standalone` means incompatible with container execution, not mock-only or server-free. `settings_only` means settings without mesh/solve work, not no Fluent session. +- `rest_server` identifies live web-server tests. Read `rest_server_connection` and `solver_session_grpc_rest` fixtures for launch, endpoint, and authentication requirements; the marker alone does not start or skip a server. +- Inspect fixture dependencies in `tests/conftest.py` before classifying a test as offline. `tests/fluent_fixtures.py` supplies helpers for generated Fluent journals, not the ordinary pytest fixture registry. +- The autouse fixture changes the working directory to `tmp_path`, sets test configuration, and copies local certificates when present. +- Install the package and `tests` extra for pytest; readers need `reader` (`h5py`), semantic search needs `search` (`nltk`), and UI needs `ui` / `ui-jupyter`. Case-data downloads, generated APIs, licenses, Docker, and live Fluent are separate requirements; test extras alone do not provide them. ## Feature-to-test map -Use this as a quick routing guide before choosing a test target: - -- Launch and session lifecycle: `test_launcher.py`, `test_launcher_remote.py`, `test_fluent_session.py`, `test_session.py`, `test_pre_post_session.py` -- Meshing workflows: `test_meshing_workflow.py`, `test_new_meshing_workflow.py`, `test_meshing_utilities.py`, `test_pure_mesh_vs_mesh_workflow.py`, `test_server_meshing_workflow.py` -- Solver and solver-mode behavior: `test_solution_variables.py`, `test_solvermode`, `test_tui_api.py`, `test_public_api.py` -- Fields and reduction: `test_field_data.py`, `test_reduction.py`, `test_solution_variables.py`, `test_physical_quantities.py` -- Settings and datamodel API: `test_settings_api.py`, `test_settings_reader.py`, `test_datamodel_api.py`, `test_datamodel_service.py`, `test_builtin_settings.py` -- File and transfer behavior: `test_file_session.py`, `test_file_transfer_service.py`, `test_datareader.py`, `test_casereader.py` -- Search and API browsing: `test_search.py` -- API and object surfaces: `test_flobject.py`, `test_rp_vars.py`, `test_public_api.py` - -Concrete examples: - -- Reduction work first checks `src/ansys/fluent/core/fields/reduction.py` and then `tests/test_reduction.py`. -- Field-data work first checks `src/ansys/fluent/core/fields/live_field_data.py` and then `tests/test_field_data.py`. -- Search work first checks `src/ansys/fluent/core/search.py` and then `tests/test_search.py`. -- File transfer work first checks `src/ansys/fluent/core/file_transfer_service.py` and then `tests/test_file_transfer_service.py`. - -This is not exhaustive, but it gives a stable map from feature area to the most likely test cluster. - -Use this structure to choose the closest validation path, not a broad one. +Repository-relative candidates, not guarantees that whole files are cheap/server-free. Source owners are in `devel/agents/architecture.md`. + +- Launch and session lifecycle: `tests/test_launcher.py`, `tests/test_launcher_remote.py`, `tests/test_fluent_session.py`, `tests/test_session.py`, `tests/test_pre_post_session.py` (mixed unit/live coverage). +- Connections/security/errors: `tests/test_grpc_security_options.py`, `tests/test_error_handling.py`; config: `tests/test_config.py`. +- Meshing workflows: `tests/test_meshing_workflow.py`, `tests/test_new_meshing_workflow.py`, `tests/test_meshing_utilities.py`, `tests/test_pure_mesh_vs_mesh_workflow.py`, `tests/test_server_meshing_workflow.py` (live/version-sensitive). +- Meshing launch/end-to-end: `tests/test_meshingmode/test_meshing_launch.py`, `tests/test_cad_to_post_wtm.py`, `tests/test_cad_to_post_ftm.py` (live). +- Solver and solver-mode behavior: `tests/test_solution_variables.py`, `tests/test_solvermode`, `tests/test_tui_api.py`, `tests/test_public_api.py`; variants: `tests/test_aero_session.py`, `tests/test_icing_session.py`, `tests/test_pre_post_session.py` (live; solvermode requires its flag). +- Fields and reduction: `tests/test_field_data.py`, `tests/test_reduction.py`, `tests/test_solution_variables.py`, `tests/test_physical_quantities.py` (live paths; select mock checks where present). +- Settings and datamodel API: `tests/test_settings_api.py`, `tests/test_settings_reader.py`, `tests/test_datamodel_api.py`, `tests/test_datamodel_service.py`, `tests/test_builtin_settings.py`, `tests/test_mapped_api.py`, `tests/test_creatable.py`, `tests/test_preferences.py` (mostly live/model-dependent). +- Settings runtime/cache/generation: `tests/test_flobject.py`, `tests/test_data_model_cache.py`, `tests/test_codegen.py`, `tests/test_type_stub.py` (mixed mock/live/generated contracts). +- File and transfer behavior: `tests/test_file_session.py`, `tests/test_file_transfer_service.py`, `tests/test_datareader.py`, `tests/test_casereader.py` (mixed live, file assets/downloads, reader extras). +- Search and API browsing: `tests/test_search.py` (mocked lookup, generated index, NLTK/downloads, and live-session selections). +- API and object surfaces: `tests/test_flobject.py`, `tests/test_rp_vars.py`, `tests/test_public_api.py` (mixed; do not assume object-model tests are offline). +- Batch/remote/scheduler: `tests/test_batch_ops.py`, `tests/test_launcher_remote.py`, `tests/test_slurm_future.py`; machine allocation: `tests/test_scheduler.py` (no Fluent). +- Events/streaming/monitors: `tests/test_events_manager.py`, `tests/test_streaming_services.py`, `tests/test_solver_monitors.py` (live). +- Parametric/coupling: `tests/parametric/test_local_parametric_setup.py` (reader/data download), `tests/parametric/test_local_parametric_run.py`, `tests/parametric/test_parametric_workflow.py`, `tests/test_systemcoupling.py`; optiSLang: `tests/integration/test_optislang/test_optislang_integration.py` (external integration). +- Expressions: `tests/expressions` (parser/builder unit tests and live smoke/integration tests); Scheme/RP/console: `tests/test_scheme_eval.py`, `tests/test_rp_vars.py`, `tests/test_pyconsole.py`; file S-expressions: `tests/test_lispy.py` (no Fluent). +- REST: `tests/test_rest.py` (mocked client/transport); parity: `tests/test_settings_grpc_rest.py` (live gRPC/web-server fixtures). No dedicated Panel/Jupyter rendering test file is currently mapped. +- Utilities/compatibility/docs: `tests/test_utils.py`, `tests/test_fluent_version.py`, `tests/test_fluent_version_marker.py`, `tests/test_deprecate.py`, `tests/test_logging.py`, `tests/test_fix_doc.py`, `tests/test_topy.py`, `tests/test_fluent_fixes.py` (check individual fixtures). + +### Cheap starting targets + +No Fluent server: `tests/test_config.py`, `tests/test_fluent_version.py`, `tests/test_fluent_version_marker.py`, `tests/test_lispy.py`, `tests/test_scheduler.py`, `tests/test_rest.py`. Package/pytest dependencies still apply. + +Mixed-file unit nodes: `tests/test_search.py::test_match_whole_word`, `tests/test_data_model_cache.py::test_data_model_cache`. Inspect bodies/transitive fixtures before expanding. diff --git a/devel/agents/workflows.md b/devel/agents/workflows.md index 211881944800..832a3cdea3e1 100644 --- a/devel/agents/workflows.md +++ b/devel/agents/workflows.md @@ -1,32 +1,29 @@ # Contributor workflow -Keep work narrow, test-driven, and repo-aware. +Follow the root rules in `AGENTS.md`; this guide adds command and maintenance details. ## Default flow -1. Identify the owning subsystem. -2. Search for the relevant symbols and tests. -3. Read only the tightest relevant sections. -4. Fix one root cause. -5. Run the cheapest validation that checks the changed behavior. -6. Check import paths and package-level exposure before escalating to heavier tests. -7. Avoid large Fluent-session tests unless the patch genuinely requires them. -8. If there is uncertainty about the correct feature mapping or fix site, ask the user instead of guessing. -9. Keep the primary objectives in view: minimal token consumption and high accuracy through targeted repo knowledge. -10. Summarize what changed and the evidence. +1. Find the owner and nearest test with targeted searches/reads; ask if uncertain. +2. Diagnose and fix the root cause within that feature, following existing patterns and runtime/generated boundaries. +3. Validate the behavior cheaply, check changed imports/exports before heavier tests, and summarize changes with evidence. Preserve user changes and instruction intent as required by the root rules. -## Repo conventions +## Ownership and commands -- Keep patches within the owning feature area. -- Prefer existing project patterns over new abstractions. -- Respect the separation between runtime code and generated code. -- Do not broaden scope for a single bug fix. +- Packaging, extras, Python support, pytest options, and tool configuration live in `pyproject.toml`; build dependencies are in `requirements/requirements_build.txt`. +- API generation logic lives in `src/ansys/fluent/core/codegen`. `codegen/allapigen.py` launches live meshing and solver-icing sessions to gather static info, then generates versioned APIs, workflow task stubs, and search index data into `config.codegen_outdir`. +- Generated output is not an ordinary runtime edit target. For a schema-output defect, update the responsible generator and validate its output contract with `tests/test_codegen.py` and the nearest downstream API test. Full regeneration needs suitable Fluent/server resources. +- Setup: editable install from `AGENTS.md`; extras/test requirements from `devel/agents/testing.md`. +- Style: `pre-commit run --files ` for a focused check; `pre-commit run --all-files` remains the canonical full check. Hook configuration is in `.pre-commit-config.yaml`; some hooks explicitly scan whole trees even with a file selection. +- CI entry points are in `.github/workflows`; helper scripts and the type-check baseline live in `.ci`. `Makefile` defines versioned `unittest-dev-*`, `unittest-all-*` (nightly), and `unittest-solvermode-*` lanes, plus `api-codegen`, `test-import`, and documentation targets. +- Treat make targets as CI/platform workflows, not portable local defaults: `make install` runs `git clean -fd`, versioned test targets clear example data with `sudo rm`, and API/docs targets assume Bash/Linux tools and may remove generated output. Inspect the target and confirm destructive cleanup before running it. +- Documentation sources are in `doc/source`; API RST generators are in `doc`, examples in `examples/00-fluent`, and changelog fragments in `doc/changelog.d` (Towncrier configuration in `pyproject.toml`). With doc dependencies installed, `make -C doc html` builds Sphinx; `BUILD_ALL_DOCS` controls API RST regeneration. Full builds can import generated APIs and execute gallery examples, so they are not a cheap default for guidance-only edits. -## Escalate when the work touches +## Keeping maps accurate -- Fluent version compatibility -- generation or schema workflows -- packaging or release behavior -- CI or platform-specific execution +- After user approval under the root maintenance rule, update moved source owners, public/legacy import routing, and test paths together. Verify paths/node IDs, not inferred names. +- Keep one home per fact: root rules, architecture source owners, testing targets/requirements, workflow commands. Load only relevant sections; keep `.github/copilot-instructions.md` a pointer. +- Classify cost from bodies/transitive fixtures and actual skip rules, not filenames or markers. +- For guidance-only changes, check referenced paths (allow explicitly generated-on-demand outputs), command definitions, retained rules, and `git diff --check`; runtime integration tests are unnecessary unless the change also affects executable behavior. -Use the root AGENTS file as the startup brief, and the deeper docs only when the task actually needs that context. +Review the relevant compatibility/schema/build/CI definitions when work touches Fluent versions, generation, packaging/releases, or platform-specific execution; escalate unresolved constraints rather than guessing. From 6d20087c855ec7287fcd935cefe8a2f7bac85fbc Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Mon, 5 Oct 2026 15:45:48 +0000 Subject: [PATCH 6/7] chore: adding changelog file 5413.maintenance.md [dependabot-skip] --- doc/changelog.d/{5413.added.md => 5413.maintenance.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/changelog.d/{5413.added.md => 5413.maintenance.md} (100%) diff --git a/doc/changelog.d/5413.added.md b/doc/changelog.d/5413.maintenance.md similarity index 100% rename from doc/changelog.d/5413.added.md rename to doc/changelog.d/5413.maintenance.md From b12e467d92a6541f70b891ce65113c2164633faf Mon Sep 17 00:00:00 2001 From: Prithwish Mukherjee Date: Tue, 6 Oct 2026 08:33:25 +0530 Subject: [PATCH 7/7] Update architecture.md. --- devel/agents/architecture.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/devel/agents/architecture.md b/devel/agents/architecture.md index 94718eb16b6a..59033a662b79 100644 --- a/devel/agents/architecture.md +++ b/devel/agents/architecture.md @@ -45,9 +45,22 @@ flowchart TB transfer -.-> files ``` -- Settings, datamodel and TUI are distinct surfaces; they share session/service infrastructure but have different wrappers and schemas. Fields use runtime APIs, not generated settings wrappers. -- Expression/naming helpers support variable access; RP/Scheme helpers use services. Parametric studies orchestrate sessions; system coupling integrates solver operations with external coupled workflows. -- UI integrates session web/Jupyter presentation. Configuration, diagnostics, utilities, shared types and example downloads support the runtime across layers; search reads the generated API index rather than being a transport. +- `solver.settings`, generated `object_model` and `session.tui` are distinct service-backed APIs with their own wrappers and schemas. +- `execution.session` wires these services into the session API to expose Fluent capabilities. +- The `fields` namespace provides field-data, reduction and solution-variable APIs. +- The `expressions` namespace constructs and evaluates expressions. +- `_variable_strategies` handles descriptor naming for expressions, fields and solution variables. +- `rpvars` provides RP-variable helpers. +- `services.scheme_interpreter` provides the Scheme interface. +- `local_parametric_study` orchestrates parametric studies across sessions. +- `system_coupling` integrates solver operations with external coupled workflows. +- `ui` integrates session web and Jupyter presentation. +- `module_config` provides runtime configuration and environment defaults. +- `diagnostics` provides logging, journaling and exception support. +- `utils` provides utilities used across runtime layers. +- `_types` defines shared types used across runtime layers. +- `examples` provides example assets and download helpers. +- `diagnostics.search` reads the generated API index; it is not a transport. ### Generation and repository tooling