[2.8] Clarify simulator and API doc signposts [skip ci]

[YuanTingHsieh]

Summary

• Clarify simulator and Job Recipe docs around simulator-managed clients, worker-process concurrency, and batch-job usage.
• Add a short Executor API signpost to direct new ML training users toward Client API and Job Recipe first.
• Add concise filter guidance for custom model update compression, pointing built-in quantization users to message quantization.

Testing

• git diff --check
• python3 -m json.tool examples/tutorials/job_recipe.ipynb > /tmp/job_recipe.json
• python3 -m json.tool examples/tutorials/flare_simulator.ipynb > /tmp/flare_simulator.json

[greptile-apps]

Greptile Summary

This PR is a documentation-only update clarifying the FL Simulator's process model (worker processes, not threads), adding batch-job usage guidance, and introducing signpost notes in the Executor API and Filters pages.

• fl_simulator.rst and flare_simulator.ipynb: Replaces misleading "same process / threads" language with accurate "separate client worker processes" wording; adds batch-scheduled experiment context and corrects the Multi-GPU section accordingly.
• job_recipe.rst and job_recipe.ipynb: Mirrors the process-model corrections in the SimEnv section and adds "batch-scheduled experiments" to the use-case list; also fixes a missing newline at end of file in the notebook.
• executor.rst and filters.rst: Adds a signpost note directing new users toward Client API / Job Recipe before Executor, and a compression guidance paragraph pointing to message_quantization and DXOFilter for custom schemes — all cross-references verified valid.

Confidence Score: 5/5

Documentation-only changes with no code modifications; safe to merge.

All changes are documentation and notebook text updates. Cross-references (client_api, job_recipe, message_quantization) were verified to resolve correctly, and the technical descriptions (worker processes vs. threads, SWAP_IN/SWAP_OUT semantics) accurately reflect the actual simulator implementation.

examples/tutorials/job_recipe.ipynb has a minor inconsistency: the brief Execution Environments bullet for SimEnv was not updated to include the batch-job context that was added to both the detailed notebook cell and job_recipe.rst.

Important Files Changed

Filename	Overview
docs/programming_guide/execution_api_type/executor.rst	Adds a signpost note directing new ML training users to Client API and Job Recipe before reaching for Executor directly; both cross-references are valid.
docs/programming_guide/filters.rst	Adds a compression guidance paragraph pointing to message_quantization for built-in quantization and DXOFilter for custom schemes; cross-reference and class name are valid.
docs/user_guide/data_scientist_guide/job_recipe.rst	Updates SimEnv description to reflect worker-process model and adds batch-job use case to both the brief list and the detailed section.
docs/user_guide/nvflare_cli/fl_simulator.rst	Comprehensively corrects thread-vs-process language throughout the simulator reference, adds batch-job context, and clarifies the -t flag semantics.
examples/tutorials/flare_simulator.ipynb	Updates the intro cell to match the revised simulator reference text; change is accurate and consistent with fl_simulator.rst.
examples/tutorials/job_recipe.ipynb	Updates the SimEnv detailed section to match job_recipe.rst, but the brief Execution Environments bullet for SimEnv still lacks the 'or in one batch job' addition present in the .rst counterpart.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[New ML Training User] --> B{Needs custom task\ncontract or framework\nintegration?}
    B -- No --> C[Client API + Job Recipe]
    B -- Yes --> D[Executor API]

    C --> E{Execution Environment}
    E --> F["SimEnv\n(local worker processes,\nbatch-friendly)"]
    E --> G["PocEnv\n(multi-process, single machine)"]
    E --> H["ProdEnv\n(distributed deployment)"]

    F --> I{T vs N}
    I -- T = N --> J[Each client stays\nin memory]
    I -- T < N --> K[Clients swapped\nin/out of worker pool\nSWAP_IN / SWAP_OUT events]

Loading

_{Reviews (4): Last reviewed commit: "Merge branch '2.8' into codex/docs-runti..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR clarifies NVFlare simulator and Job Recipe documentation by explaining the simulator-managed execution model (including worker-process concurrency and batch-job usage) and adds small “signpost” guidance to steer new users toward higher-level APIs and the right filter boundary for model update compression.

Changes:

• Update SimEnv / simulator docs and tutorial notebooks to describe simulator-managed server/clients, worker-process concurrency (historical num_threads / -t), and batch-scheduled usage.
• Add an Executor API note directing most new ML training users to Client API + Job Recipe first.
• Add concise guidance in Filters docs for implementing custom model update compression at the DXO filter boundary (and point built-in quantization users to Message Quantization docs).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
examples/tutorials/job_recipe.ipynb	Clarifies SimEnv behavior, num_threads meaning, and adds batch-job suitability guidance.
examples/tutorials/flare_simulator.ipynb	Updates intro to emphasize simulator-managed execution and batch-job start/run/exit usage.
docs/user_guide/nvflare_cli/fl_simulator.rst	Refines simulator description and updates concurrency section to explain client worker-process concurrency and swap behavior.
docs/user_guide/data_scientist_guide/job_recipe.rst	Aligns Job Recipe SimEnv docs with simulator-managed clients and batch-job usage; clarifies num_threads.
docs/programming_guide/filters.rst	Adds guidance for model update compression using DXO filters and references message quantization.
docs/programming_guide/execution_api_type/executor.rst	Adds a note positioning Executor as low-level API and pointing to Client API + Job Recipe for most users.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[YuanTingHsieh]

/build

[YuanTingHsieh]

/build