Skip to content

Latest commit

 

History

History
81 lines (62 loc) · 2.96 KB

HACKING.rst

File metadata and controls

81 lines (62 loc) · 2.96 KB
Raw

Ceygen Development

This document should serve as a reminder to me and other possible Ceygen hackers about Ceygen coding style and conventions.

Development Guidelines

Some special and important files:

  • eigen_cpp.h - low-level implementation of a tiny C++ Eigen subclass that is used to create wrappers around Cython arrays.
  • eigen_cython.pxd - exports BaseMap C++ class defined in eigen_cpp.h to Cython along with other Eigen methods.
  • dtype.{pxd,pyx} - defines the base scalar fused (template-like) type that all other functions use, along with functions to create vectors and matrices.
  • dispatch.{h,pxd} - contains fancy code and Cython declarations for so-called dispatchers: tiny helpers that call more optimized Eigen functions (in fact, the same functions with different template parameters) for column-contiguous, row-contiguous matrices and contiguous vectors.

All other *.{pxd,pyx} are public Ceygen modules.

Please always use appropriate *Dispatcher from dispatch.pxd instead of calling methods from eigen_cython.pxd directly, because declarations from eigen_cython.pxd don't contain except + keyword for performance reasons (i.e. you would leak C++ exceptions raised by Eigen code without converting them to Python exceptions).

Tests and Stress Tests

All public functions should have a unit test. Suppose you have a module ceygen/modname.pyx, then unit tests for all functions in modname.pyx should go into ceygen/tests/test_modname.py. There is a couple of "standard" environment variables recognized in tests:

  • BENCHMARK - run potentially time-consuming benchmarks of Ceygen code
  • BENCHMARK_NUMPY - also run some benchmarks with NumPy backend to see difference
  • SAVE - save timings into .pickle files that can be visualized by support/visualize_stats.py.

Releasing Ceygen

Things to do when releasing new version (let it be X.Y) of Ceygen:

Before Tagging

  1. Set version to X.Y in setup.py (around line 37)
  2. Ensure ChangeLog.rst mentions all important changes
  3. Ensure that README.rst is up-to-date
  4. (Optional) update short description in setup.py
  5. (Optional) update long description README.rst

Tagging & Publishing

  1. Do ./setup.py sdist and check contents, unpack somewhere, run tests incl. benchmarks
  2. git tag -s vX.Y
  3. ./setup.py register sdist upload --sign
  4. Build and upload docs: cd ../ceygen-doc && ./synchronise.sh
  5. If short description changed, update it manually at following places:
  6. If long description changed, update it manually at following places:

After

  1. Set version to $NEXT_VERSION-pre in setup.py
  2. Add header for the next version into ChangeLog.rst