Contributing to `PICASO`¶

PEP 8 Style Guide¶

We generally follow PEP 8 styling. Below we emphasize the “must haves” of our code.

Your code should read like a book. If you have ~10 lines of code without a comment you are commenting too infrequently.
It is really important to style function headers uniformly using NumPy style Python Docstrings. This enables sphinx to auto read function headers. Below is an example, but look here for a full list of headers.

def foo(in1, in2,in3=None):
    """
    Describe function thoroughly.

    Add any relevant citations.

    Parameters
    ----------
    in1 : int
        This variable is for something cool.
    in2 : list of float
        This variable is for something else cool.
    in3 : str,optional
        (Optional) Default=None, this variable is options.

    Returns
    -------
    int
        Cool output
    float
        Other cool output

    Examples
    --------
    This is how to use this.

    >>a = foo(5,[5.0,4.0],in3='hello')


    Warnings
    --------
    Garbage in garbage out
    """

Variable names should explain what the variable is. Avoid undescriptive names like thing1 or thing2
If you have an equation in your code it should be referenced with a paper and equation number. For example:

#now define terms of Toon et al 1989 quadrature Table 1
#https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/JD094iD13p16287
#see table of terms
sq3 = sqrt(3.)
g1      = (sq3*0.5)*(2. - w0*(1.+cosbar))       #table 1
g2      = (sq3*w0*0.5)*(1.-cosbar)                 #table 1
g3      = 0.5*(1.-sq3*cosbar*ubar0)               #table 1
lamda = sqrt(g1**2 - g2**2)                                      #eqn 21
gama  = (g1-lamda)/g2                                                     #eqn 22

Github Workflow¶

Before contributing, consider submitting an issue request. Sometimes we may already be aware of an issue and can help you fix something faster.

1) Clone the repository¶

Clone the repository that you are interested in working on.

git clone https://github.com/natashabatalha/picaso.git

This will download a copy of the code to your computer. You will automatically be in the master branch upon downloading. You can track the dev branch like so:

git checkout dev

Side note: Important distinction between ``master`` and ``dev``

master always represents the released production code. Here is the workflow we will follow. All major development will be done on branches off of dev. The only exceptions are what we call “hotfixes”, which can go directly from the fixed branch to master, and minor bugs that can be directly fixed on dev. See the overall schematic below.

2) Create a branch off of `dev` with a useful name¶

It’s likely you will be working on a specific subset of a bigger code project. Any changes you make on a new branch will not affect master or dev, so you can feel free to beat up the code without damaging anything that is fully tested.

git checkout -b myfeature dev

3) Work work work work…¶

Let’s pretend that myfeature entails working on file1.py and file2.py. After you are happy with an initial change, commit and push your changes.

#commit changes
git add file1.py file2.py
git commit -m 'added cool thing'

#switch to dev branch
git checkout dev

#merge your changes
git merge --no-ff myfeature

#delete old branch
git branch -d myfeature

#push to dev
git push origin dev

Many people ask: “How often should I commit??”. Choose something that works for you and stick to it. I try and work on smaller, individual tasks and commit when I feel I have finished something. If you try and do too much at once, your commit comments won’t make too much sense with what you have actually done. Remember, eventually someone will have to review your commits. If they are hard to parse, it will delay the merge of your work.

4) Final merge to `master`¶

master is generally a protected branch, so talk to the admin or the team before proceeding. In general, merges to master are easiest done through Github Online. Near where the branches are listed, go to “New Pull Request”. Write a description of the new dev capability, and request a merge to master. And if all good then, done!!!

Using Conda Enviornments¶

Package control and version control is a pain. To make sure everyone is running on the same enviornment it will be beneficial if we are all work in the same environment. Here are the most pertinent commands you need to know.

Create your own environment¶

To create your own environment with a specific name and python package:

conda create --name your_env_name python=3.7 -y

If you have specific environment variables that need to be tied to here, then you can specify them. For example, in PICASO there is the environment variable picaso_refdata and PYSYN_CDBS:

conda activate your_env_name
cd $CONDA_PREFIX
mkdir -p ./etc/conda/activate.d
mkdir -p ./etc/conda/deactivate.d
touch ./etc/conda/activate.d/env_vars.sh
touch ./etc/conda/deactivate.d/env_vars.sh

Edit ./etc/conda/activate.d/env_vars.sh

#!/bin/sh

export MY_VAR='path/to/wherever/you/need'

And edit ./etc/conda/deactivate.d/env_vars.sh

#!/bin/sh

unset MY_VAR

No whenever you activate your environment, your variable name will be there. Whenever you deactivate your environment, it will go away.

Export your environment¶

Another great aspect of conda enviornments is that they can be passed to one another.

conda env export > my_environment.yml

Create enviornment from a `.yml` file¶

If someone passes you an environment file, you can easily create an environment from it !

conda env create -f environment.yml

Contributing to PICASO¶