Add documentation for cone dictionary

[QCmonk]

Hello,

The documentation for what fields correspond to which cones and how to structure each variable is very sparse. Would be good if additional documentation could be added to the readme on how the "cone" variable ought to be constructed for a given problem.

[bodono]

Thanks for flagging this, I'm currently working on SCS v3.0 and I'm planning to update the docs significantly as part of that release. The cone dict is better described in the main C repo here. Is there anything in particular that's not clear?

[QCmonk]

I have looked at the documentation for the C repository which is helpful but still not sufficient I think. My difficulty is/was is its not clear how parameters in these cones corresponds to specifying that cone. Looking at for example the semidefinite programming test script where the cone parameter is specified as

K = { 'f': 10, 'l': 25, 'q': [5, 10, 0, 1], 's': [2, 1, 2, 0, 1, 10, 8], 'ep': 0, 'ed': 0, 'p': [0.25, -0.75, 0.33, -0.33, 0.2] }

My interpretation of this is that this specifies a free cone of dimension 10, a positive orthant cone ('l' for linear perhaps?) of dimension 25, four second order cones ('q' for quadratic? But then what does zero mean?) and so on. This breaks down however for the 'p' specifier which now has non-integer parameters indicating something other dimension is being specified. I suppose my point is that it is never stated anywhere as far as I can tell how one actually constructs the cone dictionary. Presumably I could dig into cvxpy and fine the answers there but this shouldn't be required when direct calls to SCS are desired.

[bodono]

Ok thanks, I will clarify this in the docs. To answer your questions:

1. Yes, 'f' corresponds to the number of primal zero / dual free entries - should be a single integer. It would be better as 'z' but it is 'f' for historical and legacy reasons now.
2. 'l' is the postive orthant (linear as you say), also a single integer.
3. q is the SOCs, you can have several so it is an array of integers, 0 is just a test to make sure the code can handle weird entries (the 0 is basically just skipped).
4. 's' corresponds to an array of positive semidefinite cones of length s * (s+1)/2 (the lower triangular elements stacked columnwise), again 0 just tests edge cases.
5. 'ep' is an integer, corresponding to the number of exponential primal cones, 'ed' is exponential dual cones with the same format. Each exp cone is of length 3, so the total number of variables in exp cones is 3 * (ep + ed).
6. p correpsonds to the power cones, each power cone is of length 3 like the exp cones, however the power cones have an associated 'power' parameter, so each one is specified as a float between [-1,1]. The use of power cones is pretty rare in practice.

[QCmonk]

Ah outstanding, thank you very much! I think it would be entirely sufficient to drop your description into the readme alongside the example cone dictionary. Closing the issue.