Development Guide

Octave-Forge Symbolic Package Development Guide

Development Philosophy

• In general, we want to be a thin layer on top of SymPy.
  • We prefer fixing upstream SymPy than hacking our own solutions (E.g., fourier/laplace transforms).
  • We prefer to follow the design choices of upstream SymPy.
• When reasonable, we want to maintain high-level compatibility with Mathworks' Symbolic Math Toolbox ("SMT").
  • E.g., we use x = sym('x') whereas SymPy would probably be x = S('x').
  • E.g., we implement vpa() and syms.
• When reasonable, we want things to behave the way an Octave user experienced with doubles would expect.
  • E.g., the * and .* methods.
  • E.g., A + 1 broadcasts the 1 to be the same shape as matrix A.

Adding new functions / designing interfaces / etc

• See "Philosophy" above.
• Do it like either SymPy or SMT or core Octave. Don't invent a new way. Unless you've thought very carefully about it.
• Can you fix SymPy instead of making the change here?
• Consider carefully the future maintenance cost of diverging from SymPy.
• Consider write expensive code in python because its faster than Octave/Matlab.
• Avoid use mpmath directly if its posible.

Testing

We have two testing frameworks:

1. regular %! Octave tests.
   • Every function should have at least one of these.
   • They should pass on the currently supported Octave and SymPy combinations.
   • Tests that will pass on future SymPy or Octave releases can be marked with xtest and a comment.
   • Ideally, they would pass when OctSymPy is running on Matlab as well (although this is currently harder to test).
2. doctests.
   • pkg install -forge doctest
   • These only need to pass on one version of SymPy and Octave (see the .travis.xml file).

Sending changes

We very much welcome contributions. Send a pull request (aka "merge request"). There are various guides for how to do this. [todo: link SymPy dev guide]. Of course, .patch files also accepted if you don't wish to use github.

Both tests are run by a continuous integration service. If you make changes, in most cases the tests will need to pass before merging your work to master.

Coding Style

Some ideas about the style we use in this code:

• no tabs (there may be some b/c I've been sloppy in the past).
• 2-spaces indent for Octave code.
• 4-spaces indent for Python code.
• 4-spaces indent for Python code, even when embedded inside strings within Octave code.
• In comparison operators use spaces in both sides A == B or A = B.
• Use space between , and ; with the next expression, [1, 2; 3, 4]

Other good practice

Its not essential but each commit should be reasonably self-contained. If you want to clean up parts of the code, do that in a separate commit. This should not be an excuse to exercise our OCD.