# Workflow Execution

This guide demonstrates how to run the bundled Ewoks workflow that computes PDF signals from an integrated XRPD dataset.

## Prerequisites

- `ewoks`, `ewokspdf`, `ewoksxrpd`, and `diffpy.pdfgetx` installed in the same environment.
- An integrated XRPD dataset exported as an NXdata group (for example generated by the `IntegrateBlissScan` task).
- A PDFgetX configuration file (`.cfg`) or a dictionary of overrides.

## 1. Inspect the demo workflow

The workflow description lives at `src/ewokspdf/workflows/demo.json`. It chains the following tasks:

1. `PdfGetXAverage`
2. `PdfGetXConfig`
3. `PdfGetXProcessor`
4. `PdfGetXSaveAscii`
5. `PdfGetXSaveNexus`

Open the file to review the wiring and adapt it if required (for example change the default output types).

## 2. Prepare the inputs

- Determine the `nxdata_url` of your dataset, e.g. `silx:///data/integrated.h5::/entry/scan/data`.
- Decide where ASCII outputs should be written (the base filename must end with `.h5`).
- Ensure your PDFgetX configuration file is accessible; keep inline overrides at hand for parameters that change per scan, such as `qmax`.

## 3. Execute with the Ewoks CLI

```bash
ewoks execute src/ewokspdf/workflows/demo.json \
  --inputs average.nxdata_url="silx:///data/integrated.h5::/entry/scan/data" \
  --inputs average.average_every=all \
  --inputs config.filename=/data/pdfgetx.cfg \
  --inputs config.pdfgetx_options_dict=@json:'{"qmin": 1.0, "qmax": 25.0}' \
  --inputs processor.info=@json:'{"wavelength": 0.1408839}' \
  --inputs save_ascii.filename=/tmp/pdf/results.h5 \
  --inputs save_nexus.nxdata_url="silx:///tmp/pdf/results.h5::/entry/1.1/"
```

The command can be launched from any directory as long as paths resolve correctly.  
All task names in the `--inputs` options map to the identifiers defined in the JSON workflow.

## 4. Inspect the outputs

- ASCII files appear next to `/tmp/pdf/results.h5` with extensions such as `.iq`, `.sq`, `.fq`, `.gr`.
- The NeXus output is created under the same HDF5 file within a group named `<detector>_PDF`. You can view it with [silx view](https://www.silx.org/doc/silx/latest/applications/silx-view.html) or any NeXus browser.

## Troubleshooting

- **`diffpy.pdfgetx couldn't be imported`** – install the wheel locally and verify it matches your Python version; PDF calculations require `diffpy.pdfgetx` 2.3+.
- **Empty output files** – check that the source NXdata contains the expected `signal` attribute and that the `average_every` value divides the number of frames.
- **Permission errors** – ensure you have write access to the destination directory before running the workflow.