Package: binarycpython
# Python module for binary_c
![docstring coverage](./badges/docstring_coverage.svg) ![test coverage](./badges/test_coverage.svg)[![DOI](https://joss.theoj.org/papers/10.21105/joss.04642/status.svg)](https://doi.org/10.21105/joss.04642)We present our package [binary_c-python](https://binary_c.gitlab.io/binary_c-python/), a population synthesis code which is aimed to provide a convenient and easy-to-use interface to the [binary_c](https://binary_c.gitlab.io/binary_c/) framework, allowing the user to rapidly evolve single stellar systems and populations of star systems. Based on earlier Perl versions by [Robert Izzard](https://robizzard.gitlab.io/), updated and extended for Python 3 by [David Hendriks](https://davidhendriks.com/), Robert Izzard. Credits to Jeff Andrews for early efforts on the python-c interface.binary_c-pythonis developed for students and scientists in the field of stellar astrophysics, who want to study the evolution of individual or populations of single and binary star systems (see the [example use-case notebooks](https://binary_c.gitlab.io/binary_c-python/example_notebooks.html) in the [online documentation](https://binary_c.gitlab.io/binary_c-python)).This is the development branch forbinary_c-pythonversion [1.0.1](https://gitlab.com/binary_c/binary_c-python/-/tree/releases/1.0.1/2.2.4) andbinary_cversion [2.2.4](https://gitlab.com/binary_c/binary_c/-/tree/releases/2.2.4).The latest release branch isbinary_c-pythonversion [1.0.0](https://gitlab.com/binary_c/binary_c-python/-/tree/releases/1.0.0/2.2.4) andbinary_cversion [2.2.4](https://gitlab.com/binary_c/binary_c/-/tree/releases/2.2.4).## Installation
Below we provide the installation instructions forbinary_c-python.### Requirements
To run this code you need to at least have installations of:Pythonversion 3.9 up to 3.12 (it’s recommended to use [Pyenv](https://github.com/pyenv/pyenv) to manage your Python versions)binary_cversion 2.2.4 (See [installation section](https://binary_c.gitlab.io/binary_c#magicparlabel-156))The Python packages that are required for this code to run are listed in therequirements.txt, which automatically gets read out bysetup.py.To build the documentation the following additional software is required:pandocavailable onhttps://pandoc.org/or viasudo apt-get install pandoc### Environment variables
Before buildingbinary_c-pythonplease make sure to have defined the following environment variables:BINARY_Cshould point to the root directory of your binary_c installationLD_LIBRARY_PATHshould include $BINARY_C/src and whatever directories are required to run binary_c (e.g. locations of libgsl, libmemoize, librinterpolate, etc.)LIBRARY_PATHshould include whatever directories are required to build binary_c (e.g. locations of libgsl, libmemoize, librinterpolate, etc.)GSL_DIRshould point to the root location where you installed GSL to. This root dir should containbin/,lib/etc### Installingbinary_c-pythonThere are several ways to installbinary_c-python:### Installation via PIP:
To install this package via pip:` pip install binarycpython `This will install the latest stable installation that is available on Pip. The version on the master branch ofbinary_c-pythonis the same version as the latest stable version on Pip.### Installation from source:
To install thebinary_c-pythonfrom source, which is useful for development versions and customisation, run` ./install.sh `This will install the package, along with all the dependencies, into the current active (virtual) python environment.### Use of code without installation
It is possible to use parts of the code without installing it, by adding the root directory of this repo to your$PYTHONPATH.Downloadbinary_c-python, via e.g.git clone https://gitlab.com/binary_c/binary_c-python.gitAdd the path to the downloaded repo to your$PYTHONPATH, via e.g.export PYTHONPATH=”~/binary_c-python:$PYTHONPATH”It will not be possible to actually run systems throughbinary_cthough.## Usage
Instructions on how to usebinary_c-pythonare available in the form of [tutorial and example use-case notebooks](https://binary_c.gitlab.io/binary_c-python/example_notebooks.html) in the [online documentation](https://binary_c.gitlab.io/binary_c-python).The documentation for the latest stable release ofbinary_c-pythonis available onhttps://binary_c.gitlab.io/binary_c-python/.The documentation forbinary_cis available onhttps://binary_c.gitlab.io/binary_c.### Usage notes
Make sure that with every change/recompilation you make inbinary_c, you also rebuildbinary_c-python. Whenever you change the source code of this package, you need to re-install it into your virtualenvironment as well.### Unit tests
After installingbinary_c-pythonfrom source you can run the unit tests to make sure the code works as it should.There are two suites of unit tests forbinary_c-python. The first includes only the actual code of the project, and is located atbinarycpython/test/main.py. The second includes only the tutorial and example notebooks, and is located atpython binarycpython/tests/test_notebooks.py.## Development:
If you want to contribute to the code, then it is recommended that you install the packages indevelopment_requirements.txt:` pip install-rdevelopment_requirements.txt `Please do not hesitate to contact us to discuss any contribution. Please seeHOW_TO_CONTRIBUTE.Some useful commands to generate documentation and coverage reports are stored in thecommands/directory.We use the following naming convention for development and release branches:`development/<binary_c-pythonversion>/<binary_cversion>releases/<binary_c-pythonversion>/<binary_cversion> `### Generating documentation
To build the documentation manually, run` ./generate_docs.sh `from within thecommands/directory. Note: this requirespandocto be installed on your machine.### Generating docstring and test coverage report
To generate the unit test and docstring coverage report, run` ./generate_reports.sh `from within thecommands/directory.## JOSS paper
We’ve written a JOSS paper forbinary_c-python, which is stored in [papers/joss/paper.pdf](https://gitlab.com/binary_c/binary_c-python/-/blob/master/papers/joss/paper.pdf).Paper review status:
[![status](https://joss.theoj.org/papers/7c43806e6d1f82c2945e12ae500f03b2/status.svg)](https://joss.theoj.org/papers/7c43806e6d1f82c2945e12ae500f03b2)## FAQ/Issues:
If you encounter an issue with the code, or if you want to suggest extra features or changes in the code, please submit an issue athttps://gitlab.com/binary_c/binary_c-python/-/issues/new.Here we provide a non-exhaustive list of some issues we encountered and solutions for these:Building issues with binary_c itself:
- see the documentation of binary_c (in doc/).
- If you have MESA installed, make sure that the$MESASDK_ROOT/bin/mesasdk_init.shis not sourced. It comes with its own version of some programs, and those can interfere with installing.When Pip install fails:
- Run the installation with-vand/or–log <logfile>to get some more info
- If gcc throws errors likegcc: error: unrecognized command line option ‘-ftz’; did you mean ‘-flto’?, this might be due to that the python on that system was built with a different compiler. It then passes the python3.6-config –cflags to the binarycpython installation, which, if done with gcc, will not work. Try a different python3.6. I suggest usingpyenvto manage python versions. If installing a version of python with pyenv is not possible, then try to use a python version that is avaible to the machine that is built with the same compiler as binary_c was built with.
- if pip installation results inNo files/directories in /tmp/pip-1ckzg0p9-build/pip-egg-info (from PKG-INFO), try running it verbose (-v) to see what is actually going wrong.
- If pip terminates with the error FileNotFoundError: [Errno 2] No such file or directory: ‘<…>/binary_c-config’ Then make sure that the path to your main $BINARY_C directory is set correctly.Other:
- When running jupyter notebooks, make sure you are running the jupyter installation from the same virtual environment.
- When the output of binary_c seems to be different than expected, you might need to rebuild this python package. Everytime binary_c is compiled, this package needs to be rebuilt too.