ares Development: Contributing!

If ares lacks functionality you’re interested in, but seems to exhibit some features you’d like to make use of, adapting it to suit your purpose should (in principle) be fairly straightforward. The following sections describe how you might go about doing this.

If you end up developing something that might be useful for others and are willing to share, you should absolutely fork ares on bitbucket. Feel free to shoot me an email if you need help getting started!

Adding new modules: general rules

There are a few basic rules to follow in adding new modules to ares that should prevent major crashes. They are covered below.

Imports

First and foremost, when you write a new module you should follow the hierarchy that’s already in place. Below, the pre-existing sub-modules within ares are listed in an order representative of that hierarchy:

  • inference
  • simulations
  • solvers
  • static
  • populations, sources
  • physics, util, analysis

It will hopefully be clear which sub-module your new code ought to be added to. For example, if you’re writing code to fit a particular kind of dataset, you’ll want to add your new module to ares.inference. If you’re creating new kinds of source populations, ares.populations, and so on. If you’re adding new physical constants, rate coefficients, etc., look at ares.physics.Constants and ares.physics.RateCoefficients.

Now, you’ll (hopefully) be making use of at least some pre-existing capabilities of ares, which means your module will need to import classes from other sub-modules. There is only one rule here:

When writing a new class, let’s say within sub-module X, you cannot import classes from sub-modules Y that lie above X in the hierarchy.

This is to prevent circular imports (which result in recursion errors).

Inheritance

You might also want to inherit pre-existing classes rather than simply making new instances of them in your own. For example, if creating a class to represent a new type of source population, it would be wise to inherit the ares.populations.Population class, which has a slew of convenience routines. More on that later.

Again, there’s only one rule, which is related to the hierarchy listed in the above section:

Parent Classes (i.e., those to be inherited) must be defined either at the same level in the hierarchy as the Child Classes or below.

This follows from the rule about imports, since a class must be either defined locally or imported before it can be inherited.