[docs] Tutorial on custom matrix type

[klamike]

The docs should have a page documenting what exactly CoolPDLP requires from the matrix type.

A simple example of a custom type and/or demonstrating how to use a matrix type from another package would be cool too.

[klamike]

@mtanneau iiuc the types you have in AcceleratedDCPowerFlows.jl would be applicable here? I guess we'd just need to use some block arrays stuff to add the power balance row, then we can solve DCOPF with your incidence matrices?

[gdalle]

I was also thinking we could split the tutorial into two pages:

• basic use
• custom types and hardware acceleration

I also wanted to look at Reactant integration

[mtanneau]

I can suggest a 3-part example around economic dispatch:

1. Baseline formulation using phase-angle formulation (sparse but high dimensional)
2. PTDF-based formulation with (dense) full PTDF matrix (lower dimensional but denser)
3. PTDF-based formulation with custom PTDF operator (lower dimensional and fast matvecs

This would (hopefully) yield something like 1 --> 2 reduces iteration count but increases per-iteration time, and 2 --> 3 keeps iteration count the same but accelerates per-iteration time.

In terms of interface, PDHG should only need matvec products with A and A' for the main algorithm, plus some row/column scaling for numerical conditioning. If we can bypass the latter, wrapping custom matrix operators should be doable enough

[gdalle]

Perhaps we should separate the tutorials from the application examples, which might be more advanced and less accessible to every user?

[mtanneau]

Let me know how I can help and what the most suitable format is :)

[klamike]

Regarding bypassing/overriding preconditioning/permutation, CoolPDLP already allows for packages to do so since we provide a dispatch point on the M parameter of MILP/ConstraintMatrix. I'll work on the generic docs first, then start on an example with DCOPF/ED.