Coding Standards

With more us of us working on Python, we need to talk about some coding standards. We do not need to do it the way KSL has, but we do need to agree on a set of coding standards. Issues include documentation of code, adding and then removal of test code, how long we keep old code around, how to present diagnostic information, etc. It is a good time to do this if we are also going to use something like GitHub.

Code Documentation

Generally, each source file in Python should begin with a Doxygen header which indicates the general purpose of the file. Each function should also have it's own Doxygen documentation, located above the function definition.

KSL and NSH have tended to comment old code out, with the words old, i.e. // OLD, to leave remnant code around.

Coding Style

KSL used a beautifier/formatter on Linux to put the code into a common style. However, this hasn't been done recently and we probably should do this again, but we need a routine which works on all systems and produces the same style. Note that different editors have different conventions, so we need to decide on a style.

Input Parameters

Parameter Naming

The typical style for an input parameter is,

Central_object.mass

When input parameters are added or changed in Python, they should adhere to the following standard:

• Capitalize the first letter of the "detailed" parameter. The remainder of the detailed parameter should all be lower case, with exception for abbreviations, e.g. SV.

• Use a period to separate the "subsystem", e.g Disk.mdot where mdot is the subsystem.

• Use underscores to separate words within the subsystem or detailed variable, e.g. Stellar_wind.v_infinity.

If one is changing the name of an input parameter, one should update the tables *old_names[] and *new_names[] in the file synonyms.c with the relevant parameter names. This will ensure that Python is backwards compatible with old .pf files using old input parameter names.

Documenting Parameters

When new parameters are added they need to be documented. Documentation for input parameters are stored in the $PYTHON/docs/parameters. Each parameter is contained in a separate .yaml file (see the official YAML website for more information, or the Get Started webpage for more information).

The general standard for documenting a new input parameter is the following form:

name: name of parameter
description: |
  Description of parameter
type: parameter type, e.g. int
unit: parameter unit, e.g. erg/s
values: allowed values for the parameter
default: default parameter value
parent:
  parameter: name of parent parameter, if applicable
file: the name of the file where the parameter is read in

It's important to note that the indentation must be kept as above to adhere to the YAML standard(?). More information about this can be found in the file $PYTHON/docs/rst/meta.rst.

Building Parameter Documentation

Provided in the $PYTHON/py_progs directory is a Python (the programming language) script to convert .yaml files into .rst files which Sphinx (see their website) can use to generate HTML/LaTeX documentation.

To build the documentation, navigate into the docs folder in a terminal and input

$ python $PYTHON/py_progs/autogenerate_rtd_pages.py

The documentation will be generated into a new directory named html. The file index.html is the homepage for the input parameter documentation.

Standard and Diagnostic Logging

Python writes a lot of information to the screen and to logfiles as part of normal operation.

The general philosophy is to write the most important information to screen (for the master MPI process only), to write the remaining information of interest to the diag files (for all MPI processes), and to write diagnostic information to describe specific data for solving bugs to a specific diagnostic file.

Functions for logging are found in xlog.c, and consist of:

• Log - sends a message to the logfile and screen,

• Log_silent - sends a message to the logfile,

• Error - sends a message prefaced with "Error:" to the logfile and screen, and

• Error_silent - sends a message prefaced with "Error:" to the logfile.

Often when one is trying to diagnose a problem, one needs to write special messages out in specific formats. In general, one SHOULD NOT write these to the logfile or to the screen using printf() statement. If one insists on doing this, one should try to remove ALL of the extra diagnostics statements prior to committing changes back to GitHub to avoid extra clutter in the code.

Instead, there are tools/subroutines in diag.c which are intended to write out diagnostics to a specific file when python is invoked with the -d switch. When this switch is used, the file "python.ext.txt" is associated with a global pointer eptr. Thus to write to this file, one can use fprintf(eptr, "str %i", int). There are also various routines in diag.c which can be used to write specific sets of information, which can in many cases be adapted to a diagnostic output of interest. If something is absent, one can write a new function. These functions assume the output can be written in the form,

Keyword  data ....

so that one can have multiple diagnostics in a single file, and easily grep values of interest.

The following functions can be found in diag.c:

• get_standard_care_factors,

• get_extra_diagnostics - controls which extra diagnostics are written out which can be set in the .pf, the current parameters are (check the input parameter docs for more details),

  • @Diag.save_cell_statistics

  • @Diag.keep_ioncycle_windsaves

  • @Diag.make_ioncycle_tables

  • @Diag.save_photons

  • @Diag.save_extract_photons

  • @Diag.print_dvds_info

  • @Diag.track_resonant_scatters

• save_photon_stats - print the various information for ncstat photons (ncstat is defined in python.h and controls how many photons to print).

• save_extract_photons - print information for a doppler shifted photon.

• save_photons - print out information for a single photon, and

• track_scatters - print out information when a photon scatters.