pint Documentation
Release 0.5.2+181.g6b8fbcd.dirty
PINT Developers
Jun 14, 2017
Contents
1
PINT
1.1 PINT is not TEMPO3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
3
2
Installation
2.1 Prerequisites . . . . . .
2.2 Installing from Source .
2.3 Running tests . . . . . .
2.4 Build the documentation
2.5 Data files . . . . . . . .
2.6 Other Makefile features
5
5
6
6
6
7
7
3
Usage
4
Contributing
4.1 Types of Contributions .
4.2 Get Started! . . . . . . .
4.3 Pull Request Guidelines
4.4 Tips . . . . . . . . . . .
5
Indices and tables
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
9
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11
11
12
13
13
15
i
ii
pint Documentation, Release 0.5.2+181.g6b8fbcd.dirty
Contents:
Contents
1
pint Documentation, Release 0.5.2+181.g6b8fbcd.dirty
2
Contents
CHAPTER
1
PINT
PINT is not TEMPO3
PINT is a project to develop a new pulsar timing solution based on python and modern libraries. It is still in active
development, but it can already produce residuals from most “normal” timing models that agree with Tempo and
Tempo2 to within ~10 nanoseconds. It can be used within python scripts or notebooks, and there are several command
line tools that come with it.
The primary reasons we are developing PINT are:
• To have a robust system to check high-precision timing results that is completely independent of TEMPO and
Tempo2
• To make a system that is easy to extend and modify due to a good design and the use of a modern programming
language, techniques, and libraries.
Read the complete PINT documentation here.
3
pint Documentation, Release 0.5.2+181.g6b8fbcd.dirty
4
Chapter 1. PINT
CHAPTER
2
Installation
Prerequisites
• Python 2.7 or 3.5 or later (Note that Python 3 support is currently not complete, but is a design goal)
• The current list of required python packages is in
– requirements.txt
– requirements_dev.txt
• The simplest way to install the prerequisites, if you are in virtualenv or want to install them in the system python
is to use pip1 :
pip install -r requirements.txt
pip install -r requirements_dev.txt
If you want to install them in your local user site-packages, rather than the system python (perhaps because you
don’t have sudo privileges), append --user to those command lines.
Some of those packages may have been already installed, for example by MacPorts. For MacPorts users, this
command will get many of the requirements:
port install py27-numpy py27-scipy py27-astropy py27-nose py27-cython py27-emcee
˓→py27-sphinx py27-sphinx_rtd_theme
You probably want to avoid having multiple versions of packages installed, to reduce confusion. Working in a
virtualenv can be helpful.
• TEMPO is not required, but if you have it installed PINT can find clock correction files in $TEMPO/clock
• Tempo2 is not required, but if you have it installed PINT can find clock correction files in $TEMPO2/clock
1
If you don’t have pip installed, this Python installation guide can guide you through the process.
5
pint Documentation, Release 0.5.2+181.g6b8fbcd.dirty
Installing from Source
The sources for pint can be downloaded from the Github repo.
First, clone the public repository:
$ git clone https://github.com/nanograv/PINT.git
Normally, you want to use the master branch, since PINT is in active development and this makes it easy to get the
latest fixes with a simple git pull.
Once you have a copy of the source, if you are using a virtualenv, or want to install PINT in your system site-packages
(may require sudo), you can install it with:
$ python setup.py install
Or, synonymously:
$ make install
Or, to install it in your local user site-packages
$ python setup.py install --user
Finally, if you want to be able to edit or pull changes and have them take effect without having to re-run setup.py,
you can install using links to the source itself, like this (again append --user if you want to install in your per-user
site-packages location). This is how most PINT developers work:
$ python setup.py develop
Running tests
To verify that your installed pint is functional, you can (and should) run the test suite. This can be done using:
make test
or:
python setup.py nosetests
Build the documentation
This is not normally needed, since the documentation is available online but you can build your own copy for offline
use:
make docs
At completion, a browser will open with the documentaion.
6
Chapter 2. Installation
pint Documentation, Release 0.5.2+181.g6b8fbcd.dirty
Data files
PINT requires detailed ephemerides for the Solar System motion and for the Earth’s rotation. Many of these files are
downloaded automatically by astropy. Others are distributed with PINT in the pint/datafiles directory or are
automatically downloaded by setup.py; the total volume is a few hundred megabytes. On installation, the data files are
copied into the install directory, so you end up with two copies (unless you install in develop mode).
PINT also requires observatory clock correction data. The PINT distribution includes a set in the datafiles directory,
but clock corrections can also be read from TEMPO or Tempo2 clock directories if they are installed.
Other Makefile features
The makefile can do several other useful things including cleaning up cruft, and building tar distributions.
$ make help
clean
clean-build
clean-pyc
clean-test
lint
test
coverage
docs
servedocs
dist
install
2.5. Data files
remove all build, test, coverage and Python artifacts
remove build artifacts
remove Python file artifacts
remove test and coverage artifacts
check style with flake8
run tests quickly with the default Python
check code coverage quickly with the default Python
generate Sphinx HTML documentation, including API docs
compile the docs watching for changes
builds source and wheel package
install the package to the active Python's site-packages
7
pint Documentation, Release 0.5.2+181.g6b8fbcd.dirty
8
Chapter 2. Installation
CHAPTER
3
Usage
Start using PINT by going through the PINT_walkthough.ipynb IPython notebook.
To see how it is used programmatically, look at examples/fit_NGC6440E.py_
You can also run it from the command line with:
pintempo --plot parfile.par timfile.tim
Use -h to get help. This is not fully developed yet, so extensions to this (like a nice GUI) are most welcome.
9
pint Documentation, Release 0.5.2+181.g6b8fbcd.dirty
10
Chapter 3. Usage
CHAPTER
4
Contributing
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions
Report Bugs
Report bugs at https://github.com/nanograv/pint/issues.
If you are reporting a bug, please include:
• Your operating system name and version.
• The output of pint.__version__ and pint.__file__
• Any details about your local setup that might be helpful in troubleshooting,
such as the command used to install PINT and whether you are using a virtualenv. * Detailed steps to reproduce the
bug, as simply as possible.
Fix Bugs
Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants
to implement it.
Implement Features
Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to
whoever wants to implement it.
11
pint Documentation, Release 0.5.2+181.g6b8fbcd.dirty
Write Documentation
pint could always use more documentation, whether as part of the official pint docs, in docstrings, or even on the web
in blog posts, articles, and such.
Submit Feedback
The best way to send feedback is to file an issue at https://github.com/nanograv/pint/issues.
If you are proposing a feature:
• Explain in detail how it would work.
• Keep the scope as narrow as possible, to make it easier to implement.
• Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!
Ready to contribute? Here’s how to set up pint for local development.
1. Fork the pint repo on GitHub.
2. Clone your fork locally:
$ git clone [email protected]:your_name_here/pint.git
3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up
your fork for local development:
$
$
$
$
$
mkvirtualenv pint
cd pint/
pip install -r requirements_dev.txt
pip install -r requirements.txt
python setup.py develop
4. Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
5. When you’re done making changes, check that your changes pass the tests. Also check that any new docs are
formatted correctly:
$ make test
$ make docs
6. Commit your changes and push your branch to GitHub:
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
7. Submit a pull request through the GitHub website.
8. The maintainers will review and comment on the PR. If accepted, it will be merged into the master branch.
12
Chapter 4. Contributing
pint Documentation, Release 0.5.2+181.g6b8fbcd.dirty
Pull Request Guidelines
Before you submit a pull request, check that it meets these guidelines:
1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function
with a docstring, and add the feature to the list in README.rst.
3. The pull request should work for Python 2.7 and 3.5+. Check https://travis-ci.org/nanograv/pint/pull_requests
and make sure that the tests pass for all supported Python versions.
Tips
To track and checkout another user’s branch:
$ git remote add other-user-username https://github.com/other-user-username/pint.git
$ git fetch other-user-username
$ git checkout --track -b branch-name other-user-username/branch-name
4.3. Pull Request Guidelines
13
pint Documentation, Release 0.5.2+181.g6b8fbcd.dirty
14
Chapter 4. Contributing
CHAPTER
5
Indices and tables
• genindex
• modindex
• search
15