servicex

ServiceX

Overview

Provide concise, correct func_adl query patterns for ServiceX on ATLAS xAOD, with best practices for selections, outputs, and deliver usage.

Workflow

1. Identify the dataset type and base query.
   • Use FuncADLQueryPHYSLITE for PHYSLITE or OpenData.
   • Use FuncADLQueryPHYS for PHYS or other derivations.
2. Build a top-level Select that gathers all required collections and singletons.
   • Apply object-level filters with nested .Where inside this Select.
   • Do not pick columns yet.
3. Apply event-level filtering with a top-level .Where after the collections Select.
4. Create a final top-level Select that returns a single dictionary of output columns.
   • Convert units to standard LHC units (GeV, meters, etc.).
   • Never return a nested dictionary.
5. Use deliver once with NFiles=1 by default and appropriate dataset source(s).
6. Make sure that the layout of the data that will be returned is remembered - downstream tasks that want to work with the data will need to understand it.

Core Rules

• Prefer two top-level Select calls: collections first, output columns second.
• Filter objects with nested .Where; filter events with a top-level .Where.
• Use a single final Select that returns a dictionary of outputs.
• Do not use awkward functions inside ServiceX queries.
• Use dataset.Rucio for rucio DIDs and dataset.FileList for URL lists.
• Always set NFiles=1 by default.
• For fetches where cache bypass matters, use ignore_local_cache=True in deliver.
• If a transform fails and logs are required, respond with HELP USER.
• Ensure func_adl_servicex_xaodr25 is listed as a dependency in the active project and installed in the current virtual environment before running or generating code that uses it.
• When using xAOD tool helpers, add hep-llm-helpers>=1.0.0b1 to the active project; standalone PEP 723 scripts must list it in their dependency block, and imports use hep_llm_helpers.xaod_hints.
• When defining an xAOD accessor, the Python variable assigned by make_tool_accessor must exactly match its function_name (for example, tag_weight = make_tool_accessor(..., function_name="tag_weight", ...)); use that same name in the later query. A mismatch causes an unknown-type translation error.
• In standalone-script metadata, declare jinja2 explicitly if the environment requires it for func_adl_servicex_xaodr25 usage.