Documentation: GPU for the indirect method (flows and shooting) #976

Summary

The documentation covers the GPU for the direct method only. The page GPU (docs/src/solve/gpu.md) walks through solve(ocp; modeler=:exa_gpu, …): prerequisites, a worked problem, descriptive and explicit modes, which combinations work, performance notes.

The indirect method has nothing equivalent. The Flows overview has a short section "CPU and GPU" (docs/src/flows/overview.md) that says Flow(ocp, law; method=:gpu) exists, that the initial state and costate must be CuArrays, and sends the reader to the GPU flows page of CTFlows. A reader who wants to shoot on the GPU has no worked example in this documentation.

Proposal

Add a page (or a section next to the direct one) on the GPU for flows and shooting, built like the direct page:

• prerequisites (CUDA, Mooncake, the integrator package) and the method=:gpu keyword of the constructor (not of the call);
• one worked problem: build Flow(ocp, law; method=:gpu), give CuArray initial state and costate, integrate, and check the result against the CPU flow;
• a shooting function evaluated on the GPU, with the solver of the nonlinear system on the CPU or GPU (to be checked: what CTFlows supports and what is useful in practice);
• what does not work (CPU arrays with method=:gpu, Mooncake not loaded) and the error the user gets;
• performance notes: when it pays off (large dimension or many trajectories), consistent with Mooncake on CPU (method=:cpu + ad_backend=AutoMooncake()): fails on SubArray tangents, and only pays off for large dimensions CTFlows.jl#448 (Mooncake on CPU) and the ensemble flows of Ensemble flows — batch API for multiple shooting, globalization, and ensemble optimal control CTFlows.jl#341.

Constraints

• The GPU blocks cannot be executed by the usual docs build: the direct page runs on the occidata runner (see Make gpu.md executable (@example) and decide on a GPU-backed docs build for dev/stable #885 and ci: opt this repo's docs build into the GPU upgrade pass (#885 part 2) #946). The new page should follow the same mechanism, with the output of the last run shown and checked by @asserts on the runner.
• Depends on the CTFlows side: Flow(ocp, law; method=:gpu): obscure MethodErrors at call time (Mooncake not loaded, or CPU arrays) CTFlows.jl#436 (obscure MethodErrors of method=:gpu) is closed, so the errors can be quoted once released; the "CPU and GPU" section of the Flows overview, which says the error "does not name the cause yet", must then be updated.

Part of the final read tracked in #968.