Organize pvm2sdp, sdp2input & sdpb: IO format, naming etc.

[vasdommes]

This is an umbrella issue for pvm2sdp/sdp2input formats, naming and other things that could be improved.

TL;DR

• Binary input for sdpb #79
• Combine pmp2sdp and sdpb into a single executable? #78
• Add --writeSolution=z option to SDPB, write to output z.txt #185
• Better names. sdp2input is misleading. Something like sdp2input -> pmp2sdp?
• If no one needs pvm2sdp anymore (TODO check), remove it? UPD: at least one group is still using it.
• New pmp2sdp executable instead of separate sdp2input and pvm2sdp #178
• If pmp2sdp --input is a directory, process all files inside it #108
• Realistic end-to-end tests for sdp2input + sdpb #109
• Optimize reading block info (dim and num_points) from sdp.zip #110
• Benchmarks for reading/writing sdp.zip #111

More details

Input

We have two converters, pvm2sdp and sdp2input, both generating the same SDP format (zip with JSON files for each block), which serves as SDPB input. We can implement binary SDP instead of JSON to make it more compact and fast, see #79

These converters use different mathematical formulations (equation numbers taken from SDPB Manual):

• (2.2) Maximize $b_0 + b \cdot y$ over $y \in \mathcal{Z}^N$
  such that $M^0_j(x)+\sum y_n M^n_j(x) \succeq 0$
• (3.1) Maximize $a \cdot z$ over $z \in \mathcal{Z}^{N+1}$
  such that $n \cdot z = 1$ and $\sum z_n W^n_j(x) \succeq 0$

One can easily translate from (2.2) to (3.1) and back using the normalization condition $n \cdot z = 1$.

Most of users are now using sdp2input.
If no one needs pvm2sdp anymore (TODO check), we can remove it.

To get rid of unnecessary disk reads/writes, we can combine all into a single executable, see #78

SDPB

SDPB operates in terms of $y$ variable, i.e. formulation (2.2).
It also writes $y$ to output y.txt

Meanwhile, $z$ makes more physical sense, so end users usually have to convert $y \to z$ after running SDPB.

SDPB can do it and write z.txt, if it has normalization vector $(n_0..n_N)$.
Normalization vector is read from sdp2input input.

We can do as follows:

• sdp2input input writes optional normalization.json file to SDP.zip
• If SDPB is called with --writeSolution=z (or --writeSolution=x,y,z), it remembers normalization and then utilizes it to calculate and write z.txt.

Naming

Current naming is terribly inconsistent.
pvm2sdp: we convert PVM (Polynomial Vector Matrix) to SDP (sdpb input format).
sdp2input: we convert sdp (which is not sdpb input format, but a bunch of positive matrices with prefactor!) to sdpb input.

By the way, in spectrum pvm2sdp input format is called PVM (Polynomial Vector Matrix), and sdp2input format is called PMP (Positive Matrix with Prefactor):

sdpb/src/spectrum/handle_arguments.cxx

Lines 33 to 34 in fbbefbf

	"Format of input file: Either PVM (Polynomial Vector "
	"Matrix), or PMP (Positive Matrix with Prefactor).");

In SDPB manual and paper, however, PMP stands for "Polynomial Matrix Program" (which describes both pvm2sdp and sdp2input).

I would say, as in paper and manual, that generally we are converting PMP to SDP. So probably we should have a (universal?) converter called pmp2sdp.

[vasdommes]

In order to avoid name collision between Polynomial Matrix Program and Positive Matrix with Prefactor, we can call them PMP and PMWP, respectively.