Contributing¶

We’d welcome contributions to the Convex.jl package. Here are some short instructions on how to get started. If you don’t know what you’d like to contribute, you could

• take a look at the current issues and pick one. (Feature requests are probably the easiest to tackle.)

Then submit a pull request (PR). (Let us know if it’s a work in progress by putting [WIP] in the name of the PR.)

• Take a look at our exising usage examples and add another in similar style.
• Submit a PR. (Let us know if it’s a work in progress by putting [WIP] in the name of the PR.)
• We’ll look it over, fix up anything that doesn’t work, and merge it!

Here are the steps to add a new function or operation (atom) to Convex.jl. Let’s say you’re adding the new function $$f$$.

• Take a look at the nuclear norm atom for an example of how to construct atoms, and see the norm atom for an example of an atom that depends on a parameter.
• Copy paste (eg) the nuclear norm file, replace anything saying nuclear norm with the name of the atom $$f$$, fill in monotonicity, curvature, etc. Save it in the appropriate subfolder of src/atoms/.
• Add as a comment a description of what the atom does and its parameters.
• The most mathematically interesting part is the conic_form! function. Following the example in the nuclear norm atom, you’ll see that you can just construct the problem whose optimal value is $$f(x)$$, introducing any auxiliary variables you need, exactly as you would normally in Convex.jl, and then call cache_conic_form! on that problem.
• Add a test for the atom so we can verify it works in test/test_<cone>, where <cone> matches the subfolder of src/atoms.
• Submit a PR, including a description of what the atom does and its parameters. (Let us know if it’s a work in progress by putting [WIP] in the name of the PR.)
• We’ll look it over, fix up anything that doesn’t work, and merge it!

Fixing the guts¶

If you want to do a more major bug fix, you may need to understand how Convex.jl thinks about conic form. To do this, start by reading the Convex.jl paper. Then read the conic form code:

• We define data structures for conic objectives and conic constraints, and simple ways of combining them, in conic_form.jl
• We convert the internal conic form representation into the standard form for conic solvers in the function conic_problem.
• We solve problems (that is, pass the standard form of the problem to a solver, and put the solution back into the values of the appropriate variables) in solution.jl.

You’re now armed and dangerous. Go ahead and open an issue (or comment on a previous one) if you can’t figure something out, or submit a PR if you can figure it out. (Let us know if it’s a work in progress by putting [WIP] in the name of the PR.)

PRs that comment the code more thoroughly will also be welcomed.