describe cones interface and scripts more in docs

docs/make.jl

@@ -12,7 +12,7 @@ makedocs(
         "Modeling" => "modeling.md",
         "Solving" => "solving.md",
         "Examples" => "examples.md",
-        "Scripts" => "scripts.md",
+        "Benchmarks" => "benchmarks.md",
         "API reference" => [
             "api/hypatia.md",
             "api/cones.md",

docs/src/api/cones.md

@@ -70,7 +70,7 @@ WSOSInterpEpiNormEucl
 WSOSInterpEpiNormOne
 ```
 
-### PosSemidefTriSparse helpers
+### Helpers for PosSemidefTriSparse
 
 ```@docs
 PSDSparseImpl

docs/src/benchmarks.md

@@ -0,0 +1,10 @@
+# Benchmarking scripts
+
+In the [benchmarks folder](https://github.com/chriscoey/Hypatia.jl/tree/master/benchmarks), we have scripts for running performance benchmarks on instances derived from our examples.
+See [Examples](@ref) for descriptions of our examples, and see the [examples folder](https://github.com/chriscoey/Hypatia.jl/tree/master/examples) for the instances, which are generated on-the-fly.
+The two types of benchmarks we run are:
+- natural versus extended formulations, for a selection of examples; see [natvsext](https://github.com/chriscoey/Hypatia.jl/tree/master/benchmarks/natvsext),
+- selected algorithmic options for the stepping procedures; see [stepper](https://github.com/chriscoey/Hypatia.jl/tree/master/benchmarks/stepper).
+We also provide scripts to analyze the raw results output from the run scripts.
+See the READMEs for simple instructions for running these scripts on your machines.
+Each run script typically takes several days to complete if running all examples, and the analysis scripts only take seconds.

docs/src/cones.md

@@ -9,11 +9,14 @@ CurrentModule = Hypatia.Cones
 Hypatia's [`Cones`](@ref) module specifies a generic cone interface that allows defining new proper cones as subtypes of [`Cone`](@ref).
 This requires implementing cone oracles as methods for the new cone type; see [Cone oracles](@ref).
 The required oracles are:
-- an initial interior point inside the cone,
-- a feasibility test, which checks whether a given point is in the interior of the cone,
-- gradient and Hessian evaluations for a logarithmically homogeneous self-concordant barrier function for the cone.
+- an initial interior point inside the cone; see [`set_initial_point!`](@ref),
+- a feasibility test, which checks whether a given point is in the interior of the cone; see [`is_feas`](@ref),
+- gradient and Hessian evaluations for a logarithmically homogeneous self-concordant barrier (LHSCB) function for the cone; see [`grad`](@ref) and [`hess`](@ref).
+
 Additional optional oracles can be specified to improve speed and numerical performance.
 Defining a new cone automatically defines its dual cone (through the `use_dual` option) also.
+See Hypatia's predefined cones in the [cones folder](https://github.com/chriscoey/Hypatia.jl/tree/master/src/Cones) for examples of how to implement a new cone type and efficient oracles.
+The implementations of the [`HypoPowerMean`](@ref) cone (which uses a primal LHSCB) and the [`WSOSInterpNonnegative`](@ref) cone (which uses a dual LHSCB) are fairly typical.
 
 ## Predefined cones