Thank you for considering contributing to SuperSCS!

Please, read the following guide before you fork this repository, or before you file a new issue.

Style guide

C coding style

SuperSCS follows the following naming convention:

Typed structures are camel-case, e.g., ScsCone and ScsData
All functions start with scs_ or superscs_; this is because C lacks namespaces, so we need to avoid name clashes with other libraries
Guards in header files should start with SCS_
All function names are lowercare, e.g., scs_init_data. Don't use names like iCantReadThis.
Function names must be as informative as possible about the underlying functionality, e.g., scs_matrix_multiply
Variables defined via preprocessor directives are all uppercase and start with SCS_ (e.g., SCS_SOLVED)
Names of unit tests start with test_
No function or variable names are allowed to start with an underscore
Give all variables, even local ones, names that reveal their designation, e.g., norm_E_Atran_yb instead of t.
Static variables are all-lowercase and separated by underscores
Write one statement per line, e.g., avoid int a=1, b=2, c;
Do not default if tests for nonzero, i.e., use if (a != 0) instead of if (a); the same holds for non-NULL tests
Write short functions (we still need to do some work towards that direction)
Prefer #if defined() instead of #ifdef
Do not hard code any data in the code; use preprocessor directives

In particular, in regard to structures, they should be written like that:

struct scs_structure {
  /* fields go here */
};
typedef struct scs_structure ScsStructure;

API Documentation in C

All non-static functions in C must be documented using the Doxygen style.

/**
 * \brief Give a brief description here
 *
 * Give a more detailed description here
 *
 * @param data explain what this parameter is about
 * @param cone explanation...
 *
 * @return returns 0 if ... and 1 if ...
 *
 */

scs_int scs_function(ScsData * data, ScsCone * cone);

Installation instructions, mathematical documentation and other non-API documentation should not be part of function/variable documentation.

Instead, you should contribute to an existing page in pages/.

Unit testing in C

Unit tests are supported and executed by a simple in-house framework.

C Tests are stored in /tests/c/ and supporting data files are found in /tests/c/data/.

The main test runner file is tests/c/test_runner_dir.c.

Tests are added as follows:

r += scs_test(&test_problem_metadata, "Metadata");

The above line adds the test test_problem_metadata which has the name Metadata.

Test functions are of type typedef bool (*unitTest_t)(char**); for example:

bool test_broyden(char** str) {
 return TEST_SUCCESS;
}

Unit tests contain assertions which are documented in unit_test_util.h.

For example:

bool test_example(char** str) {
     ASSERT_TRUE_OR_FAIL(x > 0, str, "variable `x` should be positive");
     ASSERT_EQUAL_INT_OR_FAIL(i, i_expected, str, "the value of `i` is wrong");
     ASSERT_EQUAL_FLOAT_OR_FAIL(t, t_expected, 1e-9, str, "the value of `t` is wrong");
     ASSERT_EQUAL_ARRAY_OR_FAIL(arr, arr_expected, 10, 1e-9, str, "array `arr` is not correct");
     return TEST_SUCCESS;
}

All test functions start with test_.

Comments in C

Comments in C should be like that:

/* comment goes here */

Multi-line comments should be like that:

/*
 * this is a multiple-line comment
 * which continues into the next line
 */

Version Numbers

SuperSCS uses a 3-digit version number with a major, a minor and a build number.

Version numbers are updated every time dev is merged into master.

Git

Using/creating branches

We use a simple collaboration model with two branches:

The master branch into which we merge to create a new release,
The dev (development) branch where the development takes place

Experimental branches can be created, branching out of dev.

If you need to provide some new functionality, or solve an issue:

Checkout dev
Create a new branch out of dev - give it a name like feature/parser or hotfix-issue-183
Work on that branch, write unit tests for your new functionality or tests to verify that the problem has been resolved
Create a new pull request on github and ask for someone else to have a look at your changes and merge it.

Creating an issue

Issues: code of conduct

Before creating a new issue, please make sure that the same or a very similar issue has already been filed.

In general, you shouldn't file an issue to ask a question unless:

You need to report that the documentation is unclear, wrong, outdated or insufficient (label: documentation),
You want to contribute to SuperSCS and part of the code or its sturcture is not clear (label: help-wanted).

If you simply need to ask a question...

Reporting an issue

You may report your issue using the project's issue tracker on github

In your issue report, please include the following information:

explanatory title: a clear title
description: a detailed description of the issue
steps to reproduce the issue: make a list of steps
- report the expected and actual behavior
- provide logs and the output of SuperSCS
- if logs are too lengthy, use pastebin or a similar service
- if you need to paste code, use github's markdown syntax
SuperSCS: report your SuperSCS version
Platform information: what is your operating system, Python/MATLAB version or other relevant information

Alongside, provide any additional information that will help reproduce and resolve the issue.

If possible, write a test that reproduces the error.

Labels of issues

Labels:

bug: bug report
documentation: insufficient/unclear/wrong documentation
duplicate: the same or really similar issue has been filed
enhancement: proposal for enchancement
help-wanted: a user or developer needs help or guidance with the code
invalid: invalid issue
linux: linux operating system
maxosx: Mac OS X operating system
matlab: issue related to MATLAB
memory-leak: memory leak or other memory issue
python: issue related to python
serializer-parser: issue related to the YAML serializer/parser
testing: wrong/insufficient testing
windows: windows operating system
wontfix: this issue will not be fixed

Committing to github

The following commit guidelines were inspired by the guidelines of Atom...

Use [ci skip] in the first line of your commit message to skip the CI testing
Annotate your commit message as follows (will create an emoji):
- :art: when improving the format/structure of the code
- :memo: when writing docs
- :beetle: when fixing a bug
- :racehorse: when improving performance
- :white_check_mark: when adding tests
- :wrench: when benchmarking or profiling
- :hammer: improved code or implemented new feature
- :construction: work in progress

Contributing to SuperSCS

In order to contribute and actively participate in the development of SuperSCS, you first need to fork the repository on github:

This way you will obtain a copy of SuperSCS in your user account.

You will be able to work there and submit a pull request once you complete your changes.

Before merging into master

Before merging into master, use the following checklist:

Make sure there is adequate testing.
Run make COV=1 cov and check the results
Run cppcheck
Run make docs and check the output for warnings/errors
All unit tests pass on travis CI
... and on Appveyor
Valgrind does not return any errors
The profiler (make PF=1 profile) works
The Python interface compiles and works correctly
The MEX interface works properly
All necessary files (e.g., images) have been committed
The version number has been updated in the C code
... and in Doxygen (docs/html-extra/scs-html-extra.html)
... and in Docker
Docker image builds successfully
New image uploaded on Docker Hub
A pull request has preferably been created
Changelog has been updated
Make sure there are no important issues
Check out Trello

After the pull request has been merged:

Build the documentation in master and push (make docs)
Generate the lcov report (make COV=1 cov)
If necessary, create a release
Switch back to the development branch to continue

Copy this into your pull request!

Benchmarking

Additional benchmarks are always welcome.

The standard way to report benchmarking results in SuperSCS is the Dolan-Moré plot.

Benchmarking in MATLAB

Benchmarking scripts are found in tests/profiling_matlab.

The files are organised in three main subfolders:

experimenters/ experimenters call the profile runners with different solver parameters.
profile_helpers/ functions used to run profiling problems
profile_runners/ functions which call the profile helpers with different problem parameters; these define a suite of numerical experiments

Helpers

Profile helpers are functions of the following form:

out = profile_lasso(problem, solver_options);

These accept two arguments: a problem structure with the problem parameters and a solver_options with the solver configuration (as instance of SuperScsConfig).

Runners

Runners are saved in profile_runners/. Profile runners execute a diverse collection of problems by invoking profile helper functions.

Profile runners are functions of the form:

profile_runner_logreg(solver_options, id, runner_options);

The first argument is an instance of SuperSCSConfig which is passed to all invocations of profile_runner_*.

The second argument is an (integer) identifier of the runner. The results will be stored in a .mat file at profile_results/{id}.mat.

These mat files are not put under version control.

The third argument is a structure with runner configuration parameters.

These typically are ranges of the problem parameters to be tested, number of repetitions of each run and more.

Profile runners store some general statistics in the CSV file register.csv which can be used for look-up purposes.

Experimenters

Lastly, we have the experimenters. These are stored in experimenters/.

An experimenter is a MATLAB script that calls a profile runner with different solver parameters.

Plotting results

Once an experimenter has completed successfully, we may create performance plots using perf_profile_plot

Benchmarking in Python

Docker

Making a Docker image

To build a new docker image, run the following command from within the base directory of SuperSCS:

docker image build -t kulforbes/superscs:v{version-name} .

The docker configuration is given in Dockerfile.

Table of Contents