name: wai-quantum variational and algorithm library

# The variational and algorithm library (wai/wai-quantum): a job's params
# bound exactly (engine::catalog::bind_params, a sweep fixing some of them),
# every gate's derivative by each parameter carried by the reader
# (qasm::tangents, refused with Q129 where it cannot follow one), exact
# gradients by adjoint differentiation and the parameter-shift rule,
# deterministic optimisers whose every step is a link of a digest chain, the
# variational eigensolver beside exact diagonalisation, QAOA for Max-Cut
# beside brute force (engine::variational), and the algorithm builders, each
# program checked against a reference built from its definition by the
# equivalence ladder's matrix and truth-table rungs (engine::algorithms,
# engine::equiv).
#
# Ground truth first: every gradient is held to one worked out by hand within
# its stated rounding bound, to central finite differences and to the other
# method; the spectrum to closed forms and to the trace and squared-norm
# invariants; QAOA at p = 1 to its closed form on an edge and a ring; phase
# and amplitude estimation to the Fejér distribution; the adder to a truth
# table written apart; QSVT to the Chebyshev polynomials of a signal and of a
# matrix. The answers' bytes are pinned, and the pins run on x86_64 and arm64
# here (and on every architecture wai-energy-receipts.yml's matrix runs); the
# browser engine holds the same bytes in wasm32 (wai-web-wasm.yml). The
# surfaces' tests run in wai-quantum-cli.yml, wai-quantum-service.yml and the
# contract (wai-quantum-contract.yml).

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

on:
  push:
    branches: [main]
    paths:
      - 'wai/wai-quantum/**'
      - 'rust-toolchain.toml'
      - '.github/workflows/wai-quantum-variational.yml'
  pull_request:
    paths:
      - 'wai/wai-quantum/**'
      - 'rust-toolchain.toml'
      - '.github/workflows/wai-quantum-variational.yml'

jobs:
  relevant:
    name: does this change touch it
    runs-on: linux
    outputs:
      run: ${{ steps.gate.outputs.run }}
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - id: gate
        run: |
          set -euo pipefail
          r=$(python3 scripts/pr-touches-paths.py .github/workflows/wai-quantum-variational.yml \
                "${{ github.event.pull_request.base.sha }}" \
                "${{ github.event.pull_request.head.sha }}")
          echo "this change touches the variational and algorithm library: $r"
          echo "run=$r" >> "$GITHUB_OUTPUT"

  native:
    name: parameters, gradients, optimisers, VQE, QAOA and builders · ${{ matrix.os }}, release
    needs: relevant
    if: needs.relevant.outputs.run == 'true'
    strategy:
      fail-fast: false
      matrix:
        os: [linux, linux-arm64]
    runs-on: ${{ matrix.os }}
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v5
      - name: Install Rust 1.99.1
        shell: bash
        run: |
          export PATH="$HOME/.cargo/bin:$PATH"
          command -v rustup >/dev/null 2>&1 || \
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain 1.99.1
          rustup toolchain install 1.99.1 --profile minimal
          rustup default 1.99.1
          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
      # A module filter is satisfied by any one test of the module, so each
      # new test is required by name to have run and passed.
      - name: The library's tests, each required by name
        shell: bash
        working-directory: wai/wai-quantum
        run: |
          set -euo pipefail
          cargo test --locked --release --features full --lib -- \
            engine::variational:: engine::algorithms:: engine::equiv:: \
            qasm::tests::a_gate_s_derivative_by_each_parameter_is_carried_to_it \
            qasm::tests::a_parameter_the_derivative_cannot_follow_is_refused_on_its_line \
            engine::catalog::tests::a_job_binds_its_parameters_exactly \
            engine::sets::tests::a_sweep_binds_the_parameters_params_fix \
            engine::schema::tests::the_variational_and_algorithm_answers_follow_their_schema \
            engine::refusal:: qasm::diag:: 2>&1 | tee "$RUNNER_TEMP/variational.log"
          grep -qE '^test result: ok\. [1-9][0-9]+ passed; 0 failed' "$RUNNER_TEMP/variational.log" || { echo "::error::the library's tests did not pass"; exit 1; }
          for t in engine::variational::tests::each_method_gives_the_gradient_worked_out_by_hand \
                   engine::variational::tests::both_methods_agree_with_finite_differences_and_with_each_other \
                   engine::variational::tests::a_gradient_is_the_same_bytes_every_time \
                   engine::variational::tests::what_a_gradient_cannot_take_is_refused_with_its_code \
                   engine::variational::tests::the_ansatz_is_the_variational_ml_module_s_and_so_is_its_gradient \
                   engine::variational::tests::the_spectrum_is_the_closed_form_and_keeps_the_invariants \
                   engine::variational::tests::each_optimiser_reaches_the_minimum_and_is_deterministic \
                   engine::variational::tests::an_optimisation_s_receipt_and_chain_bind_every_step \
                   engine::variational::tests::vqe_finds_the_ground_energy_diagonalisation_gives \
                   engine::variational::tests::qaoa_is_max_cut_and_finds_an_optimal_cut \
                   engine::variational::tests::the_answers_are_the_same_bytes_on_every_platform \
                   engine::variational::tests::an_optimisation_stopped_anywhere_and_gone_on_with_is_the_same_bytes \
                   engine::variational::tests::a_checkpoint_goes_on_only_from_its_own_run \
                   engine::algorithms::tests::phase_estimation_reads_the_phase_with_the_fejer_distribution \
                   engine::algorithms::tests::amplitude_estimation_reads_the_amplitude \
                   engine::algorithms::tests::the_adder_is_its_truth_table \
                   engine::algorithms::tests::signal_processing_gives_its_polynomial \
                   engine::algorithms::tests::the_singular_value_transformation_applies_the_polynomial_to_the_matrix \
                   engine::algorithms::tests::a_builder_s_refusals_name_their_code \
                   qasm::tests::a_gate_s_derivative_by_each_parameter_is_carried_to_it \
                   qasm::tests::a_parameter_the_derivative_cannot_follow_is_refused_on_its_line \
                   engine::catalog::tests::a_job_binds_its_parameters_exactly \
                   engine::sets::tests::a_sweep_binds_the_parameters_params_fix \
                   engine::schema::tests::the_variational_and_algorithm_answers_follow_their_schema \
                   engine::refusal::tests::the_documented_table_is_the_table \
                   qasm::diag::tests::the_documented_table_is_the_table; do
            grep -q "^test $t \.\.\. ok$" "$RUNNER_TEMP/variational.log" || { echo "::error::$t did not run and pass"; exit 1; }
          done
      # Without warnings: a feature gate that leaves code unreachable or a
      # value unused in one feature set shows here.
      - name: Each feature set the hosts build still builds, without warnings
        shell: bash
        working-directory: wai/wai-quantum
        env:
          RUSTFLAGS: -D warnings
        run: |
          set -euo pipefail
          cargo check --locked --no-default-features --features quantum_engine --lib
          cargo check --locked --no-default-features --features quantum_engine,quantum_receipt --lib
          cargo check --locked --no-default-features --features quantum_engine,quantum_receipt,quantum_qec,quantum_noise --lib