diff --git a/online-docs/Makefile b/online-docs/Makefile index e0fa3dfb2..c7be8ff16 100644 --- a/online-docs/Makefile +++ b/online-docs/Makefile @@ -15,6 +15,10 @@ help: .PHONY: help Makefile +linkcheck: + @$(SPHINXBUILD) -M linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile diff --git a/online-docs/README.md b/online-docs/README.md deleted file mode 100644 index edbb6995e..000000000 --- a/online-docs/README.md +++ /dev/null @@ -1,99 +0,0 @@ -COMPAS online documentation -=========================== - -The COMPAS online documentation is available at this URL: - - https://compas.science/docs - -which redirects to the underlying readthedocs page at: - - https://compas.readthedocs.io/en/latest/index.html - - -The source files for the online documentation are in the 'online-docs' directory at: - - https://github.com/TeamCOMPAS/COMPAS - - -The online documentation is provided via readthedocs. To learn more about readthedocs, visit: - - https://readthedocs.org/ - - -readthedocs uses the Sphinx document generator. To learn more about Sphinx, visit: - -https://www.sphinx-doc.org/en/master/index.html - - -The file 'requirements.txt', in the 'docs' directory, lists the software/python modules required -to build the documentation. If you plan to build the documentation locally (either so you can -test your changes before you push them to the repository, or just to view the documentation locally -rather than online), you will need to install these requirements. - -The requirements.txt file informs readthedocs what dependencies need to be installed in order for -readthedocs to build the online documentation. Some modules are commented ('#') in requirements.txt -because readthedocs either doesn't require them, or installs them by default - you will need to install -the commented modules to build the documentation locally. - -Python is required, so install that if it is not already installed. Then install 'sphinx', and the -modules listed in requirements.txt (including the ones commented). - - -Updating the documentation --------------------------- - -The documentation source file are ReST (Restructured text) files - similar to markdown. With readthedocs, -eash .rst file is compiled into a .html file, so viewable with a web browser. The documentation source -files (the .rst files) are in 'docs/online-docs' (only the 'requirements.txt' file is required by -readthedocs to be in the 'docs' directory - if that file is not in the 'docs' directory, or top-level -directory of the repo, readthedocs will not build the online documentation). - -The 'online-docs' directory contains files and sub-directories that are structured to match the structured -of the online documentation. Find the .rst file you want to modify, and make the changes in your favourite -text editor. If you need to add new .rst files, follow the existing structure, and make sure you link the -files into an index (toctree) somewhere. - - -Building the documentation locally ----------------------------------- - -Once you have Sphinx and the dependencies (from 'requirements.txt') installed, navigate to the 'docs/online-docs' -directory in you local COMPAS repo, and type: - - make clean - make html - -If everything has been installed correctly this will first remove the existing .html files for the documentation -(make clean), and then recreate them (make html). During the build process you may see some warnings that some -documents (.rst files) are not included in any toctree - that's ok, not all our pages are accessible via a table -of contents (toctree). - -If the build completes successfully, there will be .html files in the 'docs/online-docs/\_build/html' directory. -To view the newly build documentation, open 'docs/online-docs/\_build/html/index.html' with your web browser -(e.g. type 'file://path-to-compas/docs/online-docs/\_build/html/index.html' into your web browser address bar, -where 'path-to-compas' is the path to your local COMPAS repo). - -Aside: the '\_build' directory is not required on the remote repo (and will only bloat the repo), so you should -add it to your .gitignore. - - -Pushing the changes online --------------------------- - -Once you are satisfied with your changes, push the updated source files to the COMPAS repo as you would any source -changes. If things work properly, that's all you need to do: readthedocs has webhooks that will notice the change -and automatically rebuild the online documentation. The process (noticing the change, rebuilding the documentation, -then deploying the updated web pages) could take up to 15 minutes or so. If something goes wrong and the changes are -not noticed by readthedocs, or you just don't want to wait 15 minutes for your changes to appear on the web, you can -log into the readthedocs project and initiate a rebuild manually. - -The COMPAS readthedocs project name is 'compas', and the project page is: - - https://readthedocs.org/projects/compas/ - -You need to login to the readthedocs project to do anything other than look at the dashboard. Once you are logged in -you can rebuild the project. To manually start the rebuild, make sure you are on the 'Overview' page (select the -'Overview' button if you are not) and select the 'Build' button. The build may sometimes fail with an "environment" -error - the solution is to wait a few minutes and try again (readthedocs has some concurrency and timing limits). -Logon details can be found on the COMPAS slack workspace (devel\_compas\_documentation channel). - diff --git a/online-docs/README.rst b/online-docs/README.rst new file mode 100644 index 000000000..eaa3dc1b5 --- /dev/null +++ b/online-docs/README.rst @@ -0,0 +1,63 @@ +COMPAS online documentation +=========================== + +- COMPAS homepage: https://compas.science/docs +- Code documentation: https://compas.readthedocs.io/ +- COMPAS Github: https://github.com/TeamCOMPAS/COMPAS + + +Tools +----- + +- ReadTheDocs: https://readthedocs.org/ +- Sphinx: https://www.sphinx-doc.org/en/master/index.html + +Updating the documentation +-------------------------- + +1. Edit .rst files in 'docs/online-docs' +2. Follow existing structure for new files +3. Link new files to an index (toctree) + + +Building the documentation locally +---------------------------------- + +In the repository root directory: + +.. code-block:: bash + + pip install -e '.[dev]' + cd online-docs + make clean + make html + + + + +View results in 'docs/online-docs/_build/html/index.html' + +Make sure there arnt any broken links! See the build logs: + +``` +(pages/User guide/docker: line 22) ok https://stackoverflow.com/questions/23735149/what-is-the-difference-between-a-docker-image-and-a-container +(pages/Developer guide/Developer build/docker-developer: line 23) ok https://www.atlassian.com/continuous-delivery/principles/continuous-integration-vs-delivery-vs-deployment +(pages/User guide/Running COMPAS/running-via-docker: line 41) broken https://stackoverflow.com/questions/23735149/what-is-the-difference-between-a-docker-image-and-a-container#:~:text=An%20instance%20of%20an%20image,of%20layers%20as%20you%20describe.&text=You%20can%20see%20all%20your,an%20image%20is%20a%20container - Anchor '%3A~%3Atext%3DAn%20instance%20of%20an%20image%2Cof%20layers%20as%20you%20describe.%26text%3DYou%20can%20see%20all%20your%2Can%20image%20is%20a%20container' not found +(pages/User guide/docker: line 49) ok https://www.docker.com/ + +``` + + +Pushing the changes online +-------------------------- + +1. Push updated (.rst) source files to COMPAS repo (not the _build dir) +2. ReadTheDocs automatically rebuilds (takes up to 15 minutes) +3. For manual rebuild: + - Log in to https://readthedocs.org/projects/compas/ + - Go to 'Overview' page + - Click 'Build' button + +Note: If build fails with "environment" error, wait and retry. + +Logon details can be found on the COMPAS slack workspace (devel\_compas\_documentation channel). diff --git a/online-docs/conf.py b/online-docs/conf.py index 00bef9a09..65b5ae455 100644 --- a/online-docs/conf.py +++ b/online-docs/conf.py @@ -51,6 +51,7 @@ "sphinx.ext.viewcode", "sphinxarg.ext", "sphinx_tabs.tabs", + "sphinx_togglebutton", ] intersphinx_mapping = {'python': ('https://docs.python.org/3', None), diff --git a/online-docs/index.rst b/online-docs/index.rst index b5724d30b..53c531ebc 100644 --- a/online-docs/index.rst +++ b/online-docs/index.rst @@ -24,13 +24,10 @@ Contents -------- .. toctree:: - :maxdepth: 1 + :maxdepth: 4 ./pages/Getting started/getting-started - ./pages/User guide/user-guide - ./pages/Developer guide/developer-guide - Code repository Request an enhancement Report a problem @@ -44,7 +41,18 @@ Contents ./pages/quick-links -| +.. toctree:: + :maxdepth: 3 + + ./pages/User guide/user-guide + + +.. toctree:: + :maxdepth: 3 + + ./pages/Developer guide/developer-guide + + If you use COMPAS in the preparation of a publication, please :doc:`cite COMPAS <./pages/how-to-cite>`. diff --git a/online-docs/pages/Developer guide/developer-guide.rst b/online-docs/pages/Developer guide/developer-guide.rst index 9e5b36e1e..bccf930ca 100644 --- a/online-docs/pages/Developer guide/developer-guide.rst +++ b/online-docs/pages/Developer guide/developer-guide.rst @@ -5,8 +5,7 @@ TeamCOMPAS welcomes the active involvement of colleagues and others interested i the COMPAS software. We hope this Developer Guide helps anyone interested in contributing to the COMPAS software. We expect this guide to be a living document and improve along with the improvements made to the software. -This guide covers the C++ COMPAS population synthesis code. Post-processing code (Python scripts) are not (yet) covered -by this guide. +This guide covers the C++ COMPAS population synthesis code. .. toctree:: @@ -21,4 +20,4 @@ by this guide. ./changelog ./Programming style/programming-style ./Developer build/developer-building-compas - + ./git-workflow.rst diff --git a/online-docs/pages/Developer guide/git-workflow.rst b/online-docs/pages/Developer guide/git-workflow.rst new file mode 100644 index 000000000..75f6d7c71 --- /dev/null +++ b/online-docs/pages/Developer guide/git-workflow.rst @@ -0,0 +1,32 @@ +Git Workflow +============ + +If you are not familiar with ``git``, please refer to a tutorial such as `this one `_. + +In ``COMPAS`` we work in the ``dev`` branch, and use the ``master`` branch for the major version changes. The main workflow is as follows: + +1. Create a git-issue describing the tasks you want to work on (this is optional, but recommended). +2. Create a new branch from ``dev`` with a descriptive name (e.g. ``feature/issue-123``), and make a draft pull request to ``dev``. This will allow you to work on the code collaboratively and get feedback from the team. +3. Make your changes, commit them, and push them to the remote repository. Every commit will trigger the continuous integration (CI) tests. +4. Once you are happy with your changes, check that CI tests are passing, and switch the PR to ``ready for review``. This will make it clear to the team that your changes are ready for review. + +The team will review your changes, and may ask you to make some modifications. You can make these changes in the same branch, and push them to the remote repository. Once the changes are approved, the PR will be merged into ``dev``. + +CI Tests +-------- + +There are a few tests that are run automatically when you push your changes to the remote repository. These tests are: + +1. `spell-checking `_ + This ensures that docstrings and comments are correctly spelled. +2. `COMPAS compile test `_ + This ensures that COMPAS C++ and python utilities can be correctly compiled (and COMPAS can run on a fiducial binary system). +3. `COMPAS py-utils unit tests `_ + This ensures that some of the python utilities are working as expected. + + +The tests will fail if the fiducial binary system does not lead to a binary black hole merger. + +.. literalinclude:: ../../../py_tests/test_data/run.sh + :linenos: + :language: bash \ No newline at end of file diff --git a/online-docs/pages/Getting started/COMPAS-dependencies-linux.rst b/online-docs/pages/Getting started/COMPAS-dependencies-linux.rst deleted file mode 100644 index a78183fd4..000000000 --- a/online-docs/pages/Getting started/COMPAS-dependencies-linux.rst +++ /dev/null @@ -1,39 +0,0 @@ -Linux installation -================== - -You will need to install the following packages (and their prerequisites) using your package manager: - - - .. list-table:: - :widths: 25 40 35 - :header-rows: 1 - :class: bordered - - * - Package - - Ubuntu (apt) - - RHEL (yum) - * - g++ - - g++ - - gcc - * - GSL - - libgsl-dev - - gsl gsl-devel - * - Boost - - libboost-all-dev - - boost-devel - * - hdf5 - - libhdf5-serial-dev - - hdf5-devel - -For Ubuntu, type:: - - sudo apt-get install g++ libboost-all-dev libgsl-dev libhdf5-serial-dev - -For Fedora:: - - sudo dnf install gcc boost-devel gsl gsl-devel hdf5-devel - -For RHEL or CentOS:: - - sudo yum install gcc boost-devel gsl gsl-devel hdf5-devel - diff --git a/online-docs/pages/Getting started/COMPAS-dependencies-macOS.rst b/online-docs/pages/Getting started/COMPAS-dependencies-macOS.rst deleted file mode 100644 index a1f80ac7c..000000000 --- a/online-docs/pages/Getting started/COMPAS-dependencies-macOS.rst +++ /dev/null @@ -1,29 +0,0 @@ -macOS installation -================== - -It is strongly recommended to update to the latest version of macOS through the App Store. You can find what macOS version you are -using by clicking on the Apple symbol on the top left of your screen and clicking "About This Mac". - -The next step is to install or update Xcode. You can find it directly in the App Store or at `Xcode `__\ . -Note: Xcode installation requires around 20 GB of disk space. If you are low on disk space, you may consider installing a ``C++`` -compiler directly. - -Once Xcode is installed, open a Terminal, and execute the following command to install the required command line developer tools:: - - xcode-select --install - -Next, you need to install several extra libraries and python modules. Popular ways of installing them are via package managers MacPorts and Homebrew. -We give instructions for installing ``gsl``, ``boost``, and ``hdf5`` with Homebrew. To install Homebrew, run:: - - /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" - -If the installation was successful, the following should run without error:: - - brew --version - -Now install ``gsl``, ``boost``, and ``hdf5`` using Homebrew by running:: - - brew install gsl - brew install boost - brew install hdf5 - diff --git a/online-docs/pages/Getting started/COMPAS-dependencies-python.rst b/online-docs/pages/Getting started/COMPAS-dependencies-python.rst deleted file mode 100644 index 140e3ac71..000000000 --- a/online-docs/pages/Getting started/COMPAS-dependencies-python.rst +++ /dev/null @@ -1,14 +0,0 @@ -Installing Python -================= - -Python and some selected libraries are required for interfacing with the code, and also for post-processing. We recommend using ``python3``. The -``matplotlib`` and ``numpy`` libraries should also be installed. The libraries ``astropy``, ``pandas``, and ``scipy`` are also used in some other scripts. ``PyYAML``, a YAML parser and emitter for Python, is also needed if you run COMPAS via the ``runSubmit.py`` script instead of executing it directly from the terminal. - -First check if you have ``python3`` installed. If you do, typing the following should give you the version number:: - - python3 --version - -If you do not have ``python3`` installed, install it by following the instructions below for your OS: - -- For macOS, We recommend installing ``Python`` and its libraries using MacPorts. You can follow the instructions on `MacPorts Python installation on Mac `__. -- For Linux, install `python3` using your package manager (e.g. in Ubuntu, run `sudo apt-get install python3`). We recommend installing the required python libraries using the package installer ``pip``. E.g. To install ``numpy``, run `pip install numpy`; for ``h5py``, run `pip install h5py`. \ No newline at end of file diff --git a/online-docs/pages/Getting started/COMPAS-dependencies.rst b/online-docs/pages/Getting started/COMPAS-dependencies.rst deleted file mode 100644 index 6c7b66cc2..000000000 --- a/online-docs/pages/Getting started/COMPAS-dependencies.rst +++ /dev/null @@ -1,13 +0,0 @@ -Installing dependencies -======================= - -COMPAS requires a ``C++`` compiler, and the ``gsl``, ``boost``, and ``hdf5`` libraries. ``Python`` is required for the COMPAS post-processing tools. - - -.. toctree:: - :maxdepth: 1 - - ./COMPAS-dependencies-linux - ./COMPAS-dependencies-macOS - ./COMPAS-dependencies-python - diff --git a/online-docs/pages/Getting started/building-COMPAS.rst b/online-docs/pages/Getting started/building-COMPAS.rst deleted file mode 100644 index c70b8c6ab..000000000 --- a/online-docs/pages/Getting started/building-COMPAS.rst +++ /dev/null @@ -1,102 +0,0 @@ -Building COMPAS -=============== - -We first need to define an environment variable for the root directory of COMPAS in your shell start-up file for COMPAS to run properly. For example, -if you use bash as your shell, open `~/.bashrc` with a text editor and put in the following:: - - export COMPAS_ROOT_DIR=~/codes/COMPAS - -where `~/codes` should be replaced with the path to the directory where you cloned the COMPAS repository. For this to take effect, either restart your -bash session or run:: - - source ~/.bashrc - -If your shell is ``zsh`` (which is the default of macOS 10.15), set the environment variable as above in `~/.zshrc` instead of `~/.bashrc`. If your shell -is ``csh``, set the environment variable in `~/.cshrc` using:: - - setenv COMPAS_ROOT_DIR ~/codes/COMPAS - -Tip: you can check whether you have correctly defined the environment variable and whether its been active by typing into your terminal the command:: - - ECHO $COMPAS_ROOT_DIR - -This should return the directory location of the COMPAS folder (i.e. "~/codes/COMPAS"). - - - -Now go to the COMPAS source code directory:: - - cd $COMPAS_ROOT_DIR/src - -In this directory you will find the file ``Makefile``, which includes the following text to inform the compiler of the location of header files, and -the linker of the location of library files, for each of the dependencies ``gsl``, ``boost``, and ``hdf5``: - -:: - - # gsl directories - GSLINCDIR := /include - GSLLIBDIR := /lib - - # boost directories - BOOSTINCDIR := /include - BOOSTLIBDIR := /lib - - # hdf5 directories - HDF5INCDIR := /usr/include/hdf5/serial - HDF5LIBDIR := /usr/lib/x86_64-linux-gnu/hdf5/serial - -The locations given in ``Makefile`` may not match the locations of the files on your system. - - -If you installed the packages with Homebrew, the package files are likely to be found in /usr/local/opt (in directories gsl, boost, and hdf5 respectively), -but if they are not found there you will need to use Homebrew, or some other method, to locate the files. e.g. for ``boost`` using Homebrew:: - - brew info boost - boost: stable 1.72.0 (bottled), HEAD - Collection of portable C++ source libraries - https://www.boost.org/ - /usr/local/Cellar/boost/1.72.0 (14,466 files, 648.5MB) * - ... - -Note the path, which in this case is `/usr/local/Cellar/boost/1.72.0` - you will use it when you build the COMPAS executable. Repeat this for ``gsl`` and -``hdf5``, ensuring you locate the paths to the header files and library files. - -Assuming here that the locations of the header and library files in ``Makefile`` for ``gsl`` and ``hdf5`` are correct for your system, but the locations for -``boost`` are not, build the COMPAS executable (compile and link) by typing:: - - make -f Makefile BOOSTINCDIR=/usr/local/Cellar/boost/1.72.0/include BOOSTLIBDIR=/usr/local/Cellar/boost/1.72.0/lib - -The build process will run much faster if multiple processors/cores are available. To build the COMPAS executable using (e.g.) 4 cores, type:: - - make -j 4 -f Makefile BOOSTINCDIR=/usr/local/Cellar/boost/1.72.0/include BOOSTLIBDIR=/usr/local/Cellar/boost/1.72.0/lib - -Note that both ``make`` commands shown above will conduct incremental builds: they will only compile source files that have changed. To ensure a clean build -in which all source files are compiled, type:: - - make clean - make -j 4 -f Makefile BOOSTINCDIR=/usr/local/Cellar/boost/1.72.0/include BOOSTLIBDIR=/usr/local/Cellar/boost/1.72.0/lib - -The `clean` option instructs ``make`` to remove all existing object files (.o), and the COMPAS executable. A subsequent ``make`` is then forced to compile -all source files and link the resultant object files (and external libraries) into a new executable. - -Note that rather than type the ``make`` command each time you want to build COMPAS, you could create a file containing the ``make`` command, and execute that -file to build COMPAS. - -Once built, the executable can be tested with, e.g.:: - - ./COMPAS -v - -which will display the code version. - -See :doc:`../Developer guide/Developer build/COMPAS-local-build` for a detailed description of ``Makefile`` functionality. - - -:bolditalictext:`A note for Mac users:` - -If you are using MacOS and running into linking issues with the boost libraries, try:: - - make clean - make CPP=clang++ -j$(sysctl -n hw.ncpu) - -In some Mac installations, the GNU C++ compiler is not installed how we might expect, so trying to compile and link with ``clang++`` might help. - diff --git a/online-docs/pages/Getting started/dev-git-workflow.rst b/online-docs/pages/Getting started/dev-git-workflow.rst deleted file mode 100644 index 60eab0c17..000000000 --- a/online-docs/pages/Getting started/dev-git-workflow.rst +++ /dev/null @@ -1,1049 +0,0 @@ -Git Workflow for COMPAS software developers -=========================================== - - - -Contents of this document - - -`Introduction <#introduction>`__ - - -`Getting Set Up <#getting-set-up>`__ - - -`Day to Day Commands <#day-to-day-commands>`__ - - -`Lifetime of a New Feature <#lifetime-of-a-new-feature>`__ - - -`COMPAS Git Workflow <#the-compas-git-workflow>`__ - - -`Terminology <#terminology>`__ - - - - -Introduction ------------- - -Git & Github for COMPAS developers - - -For those who are unfamiliar, git and github are popular tools in the -software development community for sharing and collaborating on software -projects. - -Git is a light-weight command line tool for maintaining different -versions of software locally, and sharing those versions to remote -servers. -Github is a website that stores git-managed projects and enables -developers to collaborate centrally on many projects. - -It is a bigger topic than we can get into here, but if you are curious -you should `read more -here. `__ - -Learning git is somewhat similar to learning a new language, and it -can be difficult to fully grasp the vocabulary when starting out (which -makes searching the internet for help significantly more challenging!). -Some of the most fundamental terms are `described -below <#terminology>`__ to assist new users. - - - *TIP:* GitHub Desktop is a free app available at https://desktop.github.com/ - that provides a desktop app to visualize and simplify Github and git use. Highly recommended! - - -Purpose of this document - - -The purpose of this document is to: - -- Help COMPAS users who are new to git to get set up, -- Outline a consistent workflow for COMPAS developers in their - day-to-day use of git, and -- Provide some of the commands that are required for this workflow - -Git is very powerful, so this is only a very small subset of the -available git commands. - -This is, in some sense, a living document, meaning we are always open -to suggestions and criticism with the workflow, and seek only to find -the best option for everybody. -Please send any feedback to the `COMPAS User Google -Group `__. - -With that said, all developers should commit to learning the agreed upon -workflow, to ensure consistency and protect against conflicts which may -derail development. - - - -Outline of the COMPAS code repository - - -*Note:* If anything below doesn't make sense, try looking at the end of this document for relevant `Terminology. <#terminology>`__ - -COMPAS users who are not developers can download the source code from -the Main Repository, found at -`github.com/TeamCOMPAS/COMPAS `__ (details -can be found below). -You will only need the default ``production`` branch and do not need -to worry about what branches are. - -For developers, this repository (or 'repo') is considered "pristine", -meaning that any work done here should be in a mature stage. - -The repository contains 2 permanent branches, ``production`` and -``dev``. -All other branches are either feature or hotfix branches, whose -purpose is to either introduce some new functionality or fix a bug, -respectively, and then be deleted. - -Feature branches on the Main Repository (also called the Main Fork or -simply Main) should be ready to be tested by others. -The Main Fork is not a "sandbox" for new, experimental ideas. -You should `create your own fork <#fork-the-main-repo>`__ off of the -Main Repository if you want to have public-facing experimental work. - -This approach to the repository and workflow below are based on the -`Feature Branch -Workflow `__ -which is in common use in industry. - - - -Getting Set Up --------------- - -**Step-by-step directions for how to configure your local and remote git -repositories** - -*COMPAS Users and Developers* - - -Set up git and create a Github account - - -#. If you have not already, go to `github.com `__ - and setup an account. - -#. Check that you have a `working install of - git. `__ - -#. It is recommended, though not necessary, that you configure `Github - with - ssh `__ - as well. - This will allow you to bypass frequent login verification requests. - - - -Clone the COMPAS repository to your personal computer - - -Cloning a git repository is slightly different to downloading a code -database. -Git includes a history of changes made to a repo, and these changes -are included with a clone. -Cloning also includes pointers to the original (remote) repo, so that -changes to the remote can be easily imported to your local machine. - -#. To clone the COMPAS repo, go to the public COMPAS Github page and - click on the green ``code`` button (see below). - You can copy the repo address for ssh if you have it configured, - otherwise click ``Use HTTPS`` and copy that address. - -.. raw:: html - -

- -

- -#. In a terminal window, change directory into the location where you - plan to install COMPAS, e.g ``cd ~/git_repos/`` - -#. Type the appropriate of the following two commands into a terminal - window (pasting the repo name copied above). - - - SSH: ``git clone git@github.com:TeamCOMPAS/COMPAS.git`` - - - HTTPS: ``git clone https://github.com/TeamCOMPAS/COMPAS.git`` - -#. To confirm that it worked, run the following two commands: - -:: - - cd COMPAS - git branch - -#. If the clone finished without error, you should see as output: - -``* production`` - -At this point, if you do not plan to do any COMPAS development, you're -all set. -See `getting\_started.md `__ to see how to compile -and run COMPAS. -If you run into issues or would like to see new features implemented, -you can `contact us here. `__. -You can read on if you are curious, but if you are not invited to be a -collaborator, you will only have read-access to the repository. - -*COMPAS Developers Only* - - -*Note:* This section is very technical. Take a look at the section below on `Terminology, <#terminology>`__ if you get stuck! - -*TIP:* you can add local files to the .git/info/exclude instead of the .gitignore that is part of COMPAS dev to ignore files on your local clone - - -Join as a collaborator - - -In order to contribute to COMPAS, you will need to be added as a -collaborator. -Non-collaborators have read-only access to all of the branches. - -`Contact us here `__ to inquire -about collaborating, or reach out to one of us directly (see the `COMPAS -homepage `__ for an up-to-date list). - - - -Fork the main repo ------------------- - - -As a COMPAS developer, you are highly encouraged to create your own -personal github fork of the Main repo. -This is a second, remote repository (distinct from your local repo), -but is managed by your github account. -It serves as a public-facing 'sandbox' of your current work, where you -can share partially-developed ideas and projects with others who might -be interested in assisting, without interfering with or clogging up the -Main repo. - -On Github, go to the TeamCOMPAS/COMPAS repo and click on ``Fork`` in -the upper-right corner. -This will create a copy of the current state of the TeamCOMPAS/COMPAS -repo, including all branches and all commit histories, and place it on -your profile, identified as ``/COMPAS``. - -Since this is your personal repo, you can be as organized or -scatter-brained as you wish here. -If you work best with 50 branches, obscure names, and code scraps -everywhere, have at it. -You can also give or take away access to any other collaborators who -you might wish to contribute. -Note that for public repositories, your code will still be read-only -for everyone who is not a collaborator. - - - -Connect to your remote fork from your local repo - - -Once your fork is created, you'll want to connect it to your local -repository. -In the terminal, navigate to your COMPAS git repo and type: - -``git remote add `` - -The ```` can be found on your remote repo under the -same green 'Clone or Download' button as before. -If you have ssh configured, it will be similar to -``git@github.com:reinhold-willcox/COMPAS.git``. -The ```` is your choice, but should be informative, e.g -``reinhold_fork``. - - - -Day to Day commands -------------------- - -Basic commands for navigating local git - - -Branches allow a developer to experiment with multiple new features -simultaneously on the same code-base. -In git, branches are very lightweight and easy to manage, making them -incredibly useful. - -To view, switch, and create branches (akin to ``ls``, ``cd``, and -``mkdir``), use: - -:: - - git branch - git checkout - git checkout -b - -*Note:* Many git commands require that you are on the correct branch before executing the command - using these 3 commands regularly before running more complicated commands will save you headaches down the road! - -**Important:** A new branch is already created as a copy of current -branch, so you always need to double check that you're on the branch you -want to copy (typically, ``dev``). - - - -Committing changes - - -What git does best is to record all the small changes and edits that -accumulate as we modify code. -After many small changes, you might have a feature that you decide -isn't actually what you want, and you want to get rid of it. -Or you might have introduced a bug at some point that spans many -files, and you need to remove it without undoing all the work you've -accomplished since then. -Git makes this incredibly easy by storing small edits as "commits". -Commits, like branches, are incredibly versatile and powerful, but can -be conceptually tricky to grasp at first. - -Committing is the process of adding a selection of changes to the -history of your branch. -It is effectively saving your work, and should be done often (every -time any small fix has been made). -To perform a commit: - -#. Check that you're on the correct branch! - -``git branch`` - -#. Add the relevant files to your "index" (whatever files you've just - edited) - -``git add <...>`` - -#. Then submit the commit with a commit message. The message should be - clear and concise, to help identify exactly when certain changes were - made and undo them if necessary. - -``git commit -m "really clear message indicating all the changes you made in this commit."`` - -*Note:* A single commit should capture an entire "fix" of one kind. - -*Example:* Say you want to add a function to -a C file and its header, and you also want to update the internal -contents of a completely different function in the same C file, you -should do 2 commits. - -#. First, make the edits to the first function and header, then add and - commit - -:: - - git add file.C file.h - git commit -m "created function myFunction to do someStuff and added it to the header file" - -#. Then do the same for the second edits - -:: - - git add file.C - git commit -m "updated internal contents of thisOtherFunction to allow for specificUseCase" - -You can (and should) check the status of the current index regularly -with: - -``git status`` - -The printout is pretty self explanatory: it tells you which files have -been added, and which have been changed that you might consider adding -before committing. - -If you accidentally staged a file to your index, you can undo a -``git add`` before you have done a ``git commit`` with: - -``git reset `` - -You can also use ``git commit --amend`` to fix the most recent, -erroneous commit. - -:: - - git commit -m "previous commit which had the wrong files staged" - git add - git reset - git commit --amend - -which will open an editor where you can modify the commit message. - -The takeaway message is that branches are made up of many commits -strung together, one after another, forming a history of minor edits to -a given branch. -You can view the commit history of a branch with any of: - -:: - - git log - git log --pretty=oneline - git log --pretty=medium --graph - git log --all --decorate --oneline --graph - -(If you have some spare time/ interest, there are actually quite a few -elaborate git log setups online you can look at for inspiration). - -Looking through your git log, you may begin to appreciate the value of -clear, concise, commit messages. - - - -Merging branches - - -Creating a branch for every new idea is great, but at some point -you'll have two somewhat-finalized, distinct features on different -branches that you will want to combine into one. -To do that, you need to merge the branches. -Merging a separate branch onto your current branch adds a 'merge -commit' to the tip of your current branch, and leaves the other branch -as it was. -The two original branches are called parent branches, and the result, -appropriately, the child. -Typically, once you successfully merge, it is desirable to delete the -separate branch to keep things tidy. - -:: - - git checkout branch1 - git merge branch2 - git branch -d branch2 - -Merging can be difficult at first because, unless you are very good at -thinking ahead or very lucky, you probably have some overlap in the two -branches that you were working on. -Git has some pretty clever tools to figure out which changes to pull -into the merge commit, but if it is ambiguous (e.g if you've edited the -same part of a file in both parents), you will get a merge conflict. -You will have to manually edit the files to choose how to resolve the -conflict. -You are encouraged to make backup copies of both parent branches until -you are more comfortable. -Git has several `ways to deal with merge -conflicts; `__ -the best option for you may depend on the particular IDE you are using. - - - -Comparing branches - - -Often it is useful to see differences between branches and workspaces -without actually making any changes to either. -To accomplish this, we use the ``git diff`` command. -The arguments (or lack thereof) determine which objects are compared. - -To see all the recent changes in your working directory: - -:: - - git diff # compare working directory to index - git diff HEAD # compare working directory to tip of the current branch - git diff --cached # compare index to tip of the current branch - -To compare two branches ```` and ```` (or even a single file on -separate branches): - -:: - - git diff # compare the tips of two branches - git diff / # compare local branch to a remote branch - git diff :./file/path :./file/path # compare the same file on different branches - -For even more flexibility and control over branch/file comparisons, you -should checkout ``git difftool`` and its customizations for your -preferred text editor. - - - -Deleting branches ------------------ - - -You should become comfortable deleting branches, or else your repos -might pile up with old branches that are no longer active. -Branches are also very easy to manage in git (relative to other -version control systems), so you should practice creating new branches, -making quick edits, committing, and deleting again without worry. -To delete a branch, - -#. Navigate to any other branch - -``git checkout `` - -#. Try deleting the branch - -``git branch -d `` - -#. If that throws an error, likely there were some uncommitted/unmerged - changes (work that would be completely lost if the branch gets - deleted). - Either commit/merge the branch before deleting, or if you don't want - to keep the changes, you can force the delete with: - -``git branch -D `` - - - -Fetch other branches from a remote - - -If you followed the above workflow, you can verify that the COMPAS -repo is a designated remote fork in your local repo, nicknamed -``origin``. -You can also see any other remote forks that you have linked from your -local repo: - -``git remote -v`` - -should output something like: - -:: - - origin git@github.com:TeamCOMPAS/COMPAS.git (fetch) - origin git@github.com:TeamCOMPAS/COMPAS.git (push) - reinhold_fork git@github.com:reinhold-willcox/COMPAS.git (fetch) - reinhold_fork git@github.com:reinhold-willcox/COMPAS.git (push) - another_fork git@github.com:another-user/COMPAS.git (fetch) - another_fork git@github.com:another-user/COMPAS.git (push) - -To see all of the available branches across all your linked forks: - -``git branch -a`` - -should output something similar to - -:: - - * production - local_feature_branch - remotes/another_fork/dev - remotes/another_fork/production - remotes/another_fork/runSubmit - remotes/origin/HEAD -> origin/production - remotes/origin/dev - remotes/origin/production - remotes/origin/release - remotes/reinhold_fork/dev - remotes/reinhold_fork/git_workflow - remotes/reinhold_fork/production - -where anything not starting with "remotes/" is a local branch, and the -\* indicates your current branch. - -*Note:* The remote branch named ``origin/HEAD`` is a pointer to the ``origin/production`` branch. HEAD, when used locally, is a pointer to the most recent commit, or "tip", of the current branch. `Read more. `__ - -All of the remote branches are available to be copied locally with: - -``git checkout -b /`` - -*Example:* - -``git checkout -b myPySubmit another_fork/runSubmit`` - - - -Configuring remote tracking branches - pushing & pulling - - -**Important:** This section is crucially important, but it contains -some of the more confusing subtleties of git. -I tried to make these explicit throughout, but as a result this -section is a bit dense (sorry about that). -I highly recommend trying the commands yourself as you read through. - -It's often useful, though not required, to point local branches to a -branch on a remote repo, from which it will inherit changes. -For example, when changes occur on the ``dev`` branch of the Main -repo, you will probably want to pull them into your local ``dev`` branch -to keep up to date. - -If changes occur on the remote, your local git repo will not -automatically know about it (git does not regularly ping the remote -server with update requests like, e.g, most phone apps). -You can check for remote changes on a fork with: - -``git fetch `` - -*Warning:* This is a bit subtle - ``git fetch`` only updates -git's "local knowledge" of the remote branches, it does not affect your -local branches. -That makes it very "safe" - you can't overwrite any of your own work -with ``fetch``. -This is not true of ``git pull`` `(see below). <#git-pull>`__ - -To see which local branches are tracking remote branches, use: - -``git branch -vv`` - -which will have an output that looks similar to: - -:: - - * compas_hpc_updates eea656f [origin/compas_hpc_updates: behind 14] Removed references to dead files: - dev a110d38 [origin/dev: ahead 2, behind 12] Remove unwanted demo files (#150) - production d379be5 [origin/production] Jeff's defect repairs from previous commits that had to be read (#82) - new_branch b6aee96 generic branch to test git branch -vv, don't keep this - -#. The first column lists your local branches (the \* indicates your - current branch). -#. The second column is the unique hash that identifies the commit of - the tip of that branch (technically, it's only the beginning of the - hash, but it suffices to identify the commit). -#. If the local branch is tracking a remote branch, this will be - specified in brackets in the third column as - ``[/]``. - - - If there is a colon after the branch name with either "ahead N" or - "behind M" (or both), this describes whether the tip of the local - branch has additional commits that the remote does not, and vice - versa. - -#. If there are no brackets, the branch is not tracking anything. - - - -git pull --------- - - -If you have a branch which is "behind" the remote branch it is tracking -by some number of commits, then yours is out of date and you should -update it with: - -:: - - git checkout - git pull - -The ``git pull`` command defaults to the remote tracking branch of the -current branch (whatever was in the brackets above). -If the current branch is not tracking anything, or if you want to pull -from a different remote branch -(e.g, if ``origin/dev`` was updated and you want your -```` to pull in those updates), you can set it -explicitly: - -:: - - git checkout - git pull - -*Note:* You should regularly check that your branches are updated. If not, you should pull to avoid larger conflicts later on. - - - -git push - - -To share your local work with the other collaborators, you need to -"push" your changes to a remote repository. -Similar to ``git pull``, ``git push`` defaults to the designated -remote tracking branch, if it exists. -If not, or if you want to push to a different remote branch, you can -set it manually: - -:: - - git checkout - git push - -Pushing to your personal remote repository is a way to save all of -your commits (i.e the history of edits) somewhere off your local -computer. -This is good practice because it acts as a backup in the event -something happens to your local machine, and it also allows other -collaborators to see your work -(without having to explicitly send them your work all the time). -This should also be done often, but not necessarily for every commit. -A good rule of thumb is to push any updated branches at the end of the -day. - - - -pull requests - - -We will briefly introduce here the concept of pull requests. If -working on a remote repo, especially a shared one, it is often desirable -to block direct push access, as this could -potentially lead to bad code being introduced without proper vetting. -The solution is pull requests: the user who wrote the new code will -submit the changes as a pull request, -for another developer to review. If they pass inspection, the reviewer -can then approve the pull request and merge the changes into the remote -repo. - -Clarification of the difference between push, pull, and pull requests -can be found in the `Terminology <#terminology>`__ section below. - - - -set remote tracking branch - - -You can add or update a branch's remote tracking branch (sometimes -called the "upstream" branch) with: - -:: - - git checkout ` - git branch --set-upstream-to=/ - -*Note:* The syntax may vary slightly depending on your version of git. ``man git branch`` should be able to shed some light. - - - -Lifetime of a New Feature -------------------------- - -New feature branches - - -When beginning a new feature, you will typically want to branch off of -the most updated version of the ``dev`` branch. -Ultimately, the feature will be merged back into ``dev`` (or else -abandoned), and this will facilitate the merge later on. - -:: - - git checkout dev - git pull - git checkout -b - -The name of your branch should *clearly* describe the feature you plan -to implemented. -This will help you to keep track of where different bits of code live -once the number of branches gets large. - - - -Ongoing feature branches - - -Commit regularly as you make changes. - -:: - - git status - git add <...> - git commit -m "useful message" - -When you have made many commits and want to push your work up to the -remote, first check that you have the correct current and target -branches - -:: - - git branch -vv - git push - -If you are working on a shared remote branch, you should also pull -regularly to keep up with any changes that are made there. A safe way to -check if there are any changes, without risking overwriting your local -work, is to fetch and diff. - -:: - - git fetch - git diff HEAD / - - - -Finalized features - - -When a feature branch is nearing completion (e.g when the code is -nearly ready to be submitted into the Main Repository and tested), you -will want to ensure that it is fully up-to-date with the Main repo. -Then, push your branches up to your personal remote repo before -submitting a Pull Request. - -#. Ensure that your branch has the latest updates from ``dev``. - -:: - - git checkout dev - git pull - git checkout - git merge dev - -#. Push to your personal remote repo - -:: - - git checkout - git push --set-upstream - -#. Submit a Pull Request to the Main repo - - - Login to github and go to your personal remote repo - ``/COMPAS``. - - - Click ``Pull request`` (If you recently pushed your branch, you - could also click on ``Compare & pull request``) - - - Double check that you have selected the correct feature and target - branches. In almost all cases, the base should be - ``TeamCOMPAS/COMPAS`` with branch ``dev``, which will probably not - be the default. Then click ``Create pull request`` - - - Add a comment describing your feature and what changes you made. - If you have any particular reviewers in mind, or your feature - solves one of the Git Issues, you should link those here. Then - click ``Create pull request``, and you're all set! - -.. raw:: html - -

- -

- -Once you have created the pull request, it is up to the other team -members to review it (see below). They may ask you to fix some parts -before accepting it, so keep an eye on the pull request conversation. - - - -The COMPAS Git Workflow ------------------------ - -The above sections go over many of the available git commands that you -might find useful. -This section delves into how we apply these specifically to the COMPAS -workflow. - -Overview - - -There should always be only 2 branches on the Main Repo: -``production`` and ``dev``. -They are both permanent, and both can only be modified with pull -requests which must be approved by another COMPAS developer. - -The ``production`` branch is the current "long term service release", -meaning that it should be well-tested. -Of course, code is never truly bug-free, but this branch is the one -that the public will use, so updates should be extensively tested. - -The ``dev`` branch is where new features are joined together in -preparation for the next release. -Pull requests to ``dev`` should be made from feature branches sitting -on other remote repos (e.g the personal repo of the author). -Presumably, these new features have each been tested in isolation and -correctly do what they propose to do. -But ``dev`` is a place to confirm that all the new features combined -together still produce sensible output. - - - -Reviewing Pull Requests - - -Typically, a new feature branch will be formally reviewed when it is -submitted as a pull request into ``dev``. -Reviewers have a responsibility to check the following: - -- The code compiles without error on the usual assortment of Operating - Systems. -- The code runs without error using all default values (``./COMPAS``). -- The code runs without error on a medium-sized population of binaries. -- The new feature(s) do what they propose to do. -- All new features are explicitly mentioned (i.e nothing is fixed - quietly). -- Documentation has been updated appropriately. -- Formatting conforms to the rest of COMPAS. - -This does not all have to be done by one reviewer, but there should be a -consensus among all reviewers that all tests have been passed. - -A new release is defined by a pull request from ``dev`` to -``production`` and should involve most of the active developers. -The ``dev`` branch should be tested heavily for a variety of potential -bugs, including speed tests, different package and OS versions, and -comparisons of key plots from different papers. - - - -Terminology ------------ - -- **Commit**: A single commit records a collection of edits to one or - more files, with an associated commit message. - You can make and undo many changes before making a commit, and you - can similarly revert commits which are later deemed unnecessary. - As a verb, committing changes means to create a commit of the - changes and append that commit onto a sequence of previous commits (a - "branch", see below). - -- **Branch**: A single branch is an ordered sequence of commits. - A new commit is always appended onto the tip of a branch, and the - name of the branch is really just a pointer to this most updated - branch tip. - When a new branch is created from an old one, they initially still - point at the same commit, the tip of both (currently identical) - branches. - New commits can be applied to one branch or the other, leading to a - divergent history (which is not a bad thing). - The imagery of the shared history of commits, followed by the split - into two separate histories, readily leads to the name "branches". - A branch will often represent a place to experiment with changes in - a way that doesn't risk destroying the existing code. - Major branches will add some new functionality or some new physical - prescription, while sub-branches may pop-up to quickly test some - variation to the new functionality. - These sub-branches might be merged in to the major feature branch, - destroyed, or possibly continue on their own to be expanded into a - more major feature (and then merged in later on). - Whether the branch is merged or scrapped, it should always - `ultimately be deleted <#deleting-branches>`__ - `[1] `__ (aside - from the permanent ``production`` and ``dev`` branches). - -.. raw:: html - -

- - - -

- -- **Repository**: A Repository (or Repo) is a single storage location - for a given code base. - A single github user may have many repos for all of their different - software projects. - In our case, we have the Main Repository hosted by on Github at - `TeamCOMPAS/COMPAS. `__ - There are often many repositories for a given development project - - these can be local or remote repositories (see below), each (usually) - hosted by one the developers. - Each repo can contain different branches each with slight - variations on the code base, and these branches can be readily shared - between repos, along with their history of commits. - A Repo can be public (often called Open Source) or private. - COMPAS is Open Source, but the general public has only read-access. - Prospective contributors need to be added as a collaborator in - order to make changes and submit pull requests. - -- **Local/Remote**: Local refers to the repository on your personal - computer, while Remote refers to any repo that isn't. - Github repos (whether Main or someone else's) will be remote for - everyone. - My local computer is only local to me; from a purely git - perspective, it would be considered remote to anyone else, though - this should not come up often because other users should never have - even remote access to your personal computer. - The purpose of your personal remote fork is to be a public proxy - for your local fork, where you can add things you've worked on that - you wish to share around. - -- **Fork**: A Fork is a full copy of a repo, including all its - branches, to another location. - Most of the time, "another location" will mean elsewhere on the - github servers, since we will be Forking from the Main Repo to our - Personal Repo when we are setting up. - In our case, Forks will distinguish different users, or perhaps - groups of users (e.g Copenhagen/COMPAS). - All core developers should have a personal fork. - If you are familiar with the ``git clone`` command, this is - identical to Forking from a remote server onto your own personal - computer. - -- **Origin**: Origin is the name commonly used for the primary remote - repository. - It is configured by default whenever you clone from a repository, - so yours will probably point to the Main Repo. - If you track multiple remote forks, you should give them all - helpful, distinguishing names (e.g ``jeff_fork``, ``reinhold_fork``, - etc.) - -- **Working Directory**: The Working Directory is where a user makes - edits to files. - It has meaning in git only in reference to the Index and the most - recent commit (i.e the tip of the current branch). - Files are edited in the working directory, before being added to - the Index (or "staged"), and then finally committed to the current - branch, or HEAD (see below). - -- **Index**: The Index (aka Staging Area) exists only in the - intermediate step between editing local files and committing those - files. - Historically, other Version Control systems only allowed editing - files, and then committing those files one by one. - The issue with that is that sometimes a collection of edits of - different files logically make up one full "commit-worthy-edit". - The classic example of this is adding a function to a .C file and - it's header .h file. - If you need to revert this commit back for any reason, it makes - sense to remove both of those edits at once - you would virtually - never need to remove the function from the C file but leave it in the - header. - Adding files to the index is the way to collect all of the files - that were involved in a given series of edits that you want to treat - as one big Edit. - -- **Tracking**: The word tracking has two meanings, and could refer to - either tracked remote repositories, or tracked local files in the - current branch, and they have slightly different meanings. - - - A tracked repository is one which contains a branch which is - currently being tracked, or "upstream", of a branch in your local - repository. - By default, all the branches on a forked repository track the - branches they were forked from. - You can modify the upstream branch of a given branch to point at - any other branch you like, whether local or remote. You can also - have multiple tracked remote repositories, though any given branch - can only track at most one other branch at a time. - This is useful if you want to check out and keep up-to-date with a - branch that sits on a colleague's fork. - You can view all tracked repositories with ``git remote -v`` - - A tracked file is one that git "knows about", meaning it was - included in the last commit. - You can have other files in the same folders as your git repo - which are not tracked (if, e.g, you want to have output files from - COMPAS runs but do not want to share those around). - If you make modifications to a tracked file but don't commit it, - git will not let you leave the branch. - -- **Push, Pull, and Pull Request**: These commands form the backbone - of file-sharing across repositories. - They all cover the same conceptual idea of "taking a branch and - copying it over to a different branch on another repo." The - difference is where you are relative to the target. - You ``pull`` from a remote into your local, and you ``push`` from - your local into a remote. - For many remotes, there are protections in place to keep arbitrary - users from pushing changes ad hoc. - ``Pull-requests`` are the polite version of a ``push`` - instead of - forcing your changes onto a remote, you are asking the manager of the - remote to review your changes, and hopefully pull them into the - remote if they approve. - -- **Revert**: A revert is used when it is decided that a particular - previous commit (or perhaps several) have introduced bugs or are - otherwise no longer undesired, and we want to remove them from the - branch. - A ``git revert`` will attempt to identify the changes made in those - commits, and create a new commit to undo them. - This is a fairly advanced git command and can easily become quite - complicated, so make sure to use this one with caution, make backups - of your work, and do lots of testing before you try anything. - -- **HEAD**: HEAD is a pointer to a commit, but the specific commit it - points to moves around regularly. - In general, it refers to the tip of whichever is the current - branch. - When you make a commit to the branch, HEAD updates to the new tip. - -- **Log**: The log of a branch is the history of that branch in terms - of its commits. - The log shows when the commits occurred, who authored them, and what - the commit message stated. - - diff --git a/online-docs/pages/Getting started/getting-started.rst b/online-docs/pages/Getting started/getting-started.rst index 27dd67dec..69d9bd831 100644 --- a/online-docs/pages/Getting started/getting-started.rst +++ b/online-docs/pages/Getting started/getting-started.rst @@ -1,22 +1,189 @@ Getting started =============== -COMPAS is a platform for the exploration of populations of single stars and compact binaries formed through isolated binary evolution. -The COMPAS population synthesis code is flexible, fast and modular, allowing rapid simulation of binary star evolution. The complete -COMPAS suite includes the population synthesis code together with a collection of tools for sophisticated statistical treatment of the -synthesised populations. +To start using COMPAS, `git clone` the code, install dependencies and build COMPAS: -To start using COMPAS, get a copy of the code, and install the libraries and tools required to build and run COMPAS: +:: -.. toctree:: - :maxdepth: 1 + git clone https://github.com/TeamCOMPAS/COMPAS - ./git-details - ./COMPAS-dependencies - ./building-COMPAS - ./dev-git-workflow +Install dependencies +-------------------- + +COMPAS requires a ``C++`` compiler, and the ``gsl``, ``boost``, and ``hdf5`` libraries. ``Python`` is required for the COMPAS post-processing tools. + + +.. tabs:: + + .. tab:: Linux + + For Ubuntu, type:: + + sudo apt-get install g++ libboost-all-dev libgsl-dev libhdf5-serial-dev + + For Fedora:: + + sudo dnf install gcc boost-devel gsl gsl-devel hdf5-devel + + For RHEL or CentOS:: + + sudo yum install gcc boost-devel gsl gsl-devel hdf5-devel + + + .. tab:: MacOS + + It is strongly recommended to update to the latest version of macOS through the App Store. You can find what macOS version you are + using by clicking on the Apple symbol on the top left of your screen and clicking "About This Mac". + + The next step is to install or update Xcode. You can find it directly in the App Store or at `Xcode `__\ . + Note: Xcode installation requires around 20 GB of disk space. If you are low on disk space, you may consider installing a ``C++`` + compiler directly. + + Once Xcode is installed, open a Terminal, and execute the following command to install the required command line developer tools:: + + xcode-select --install + + Next, you need to install several extra libraries and python modules. Popular ways of installing them are via package managers MacPorts and Homebrew. + We give instructions for installing ``gsl``, ``boost``, and ``hdf5`` with Homebrew. To install Homebrew, run:: + + /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + + If the installation was successful, the following should run without error:: + + brew --version + + Now install ``gsl``, ``boost``, and ``hdf5`` using Homebrew by running:: + + brew install gsl + brew install boost + brew install hdf5 + + +Building COMPAS +--------------- + +We first need to define an environment variable for the root directory of COMPAS in your shell start-up file for COMPAS to run properly. For example, +if you use bash as your shell, open `~/.bashrc` with a text editor and put in the following:: + + export COMPAS_ROOT_DIR=~/codes/COMPAS + +where `~/codes` should be replaced with the path to the directory where you cloned the COMPAS repository. For this to take effect, either restart your +bash session or run:: + + source ~/.bashrc + +If your shell is ``zsh`` (which is the default of macOS 10.15), set the environment variable as above in `~/.zshrc` instead of `~/.bashrc`. If your shell +is ``csh``, set the environment variable in `~/.cshrc` using:: + + setenv COMPAS_ROOT_DIR ~/codes/COMPAS + +Tip: you can check whether you have correctly defined the environment variable and whether its been active by typing into your terminal the command:: + + ECHO $COMPAS_ROOT_DIR + +This should return the directory location of the COMPAS folder (i.e. "~/codes/COMPAS"). + + + +Now go to the COMPAS source code directory:: + + cd $COMPAS_ROOT_DIR/src + +In this directory you will find the file ``Makefile``, which includes the following text to inform the compiler of the location of header files, and +the linker of the location of library files, for each of the dependencies ``gsl``, ``boost``, and ``hdf5``: + +:: + + # gsl directories + GSLINCDIR := /include + GSLLIBDIR := /lib + + # boost directories + BOOSTINCDIR := /include + BOOSTLIBDIR := /lib + + # hdf5 directories + HDF5INCDIR := /usr/include/hdf5/serial + HDF5LIBDIR := /usr/lib/x86_64-linux-gnu/hdf5/serial + +The locations given in ``Makefile`` may not match the locations of the files on your system. + + +If you installed the packages with Homebrew, the package files are likely to be found in /usr/local/opt (in directories gsl, boost, and hdf5 respectively), +but if they are not found there you will need to use Homebrew, or some other method, to locate the files. e.g. for ``boost`` using Homebrew:: + + brew info boost + boost: stable 1.72.0 (bottled), HEAD + Collection of portable C++ source libraries + https://www.boost.org/ + /usr/local/Cellar/boost/1.72.0 (14,466 files, 648.5MB) * + ... + +Note the path, which in this case is `/usr/local/Cellar/boost/1.72.0` - you will use it when you build the COMPAS executable. Repeat this for ``gsl`` and +``hdf5``, ensuring you locate the paths to the header files and library files. + +Assuming here that the locations of the header and library files in ``Makefile`` for ``gsl`` and ``hdf5`` are correct for your system, but the locations for +``boost`` are not, build the COMPAS executable (compile and link) by typing:: + + make -f Makefile BOOSTINCDIR=/usr/local/Cellar/boost/1.72.0/include BOOSTLIBDIR=/usr/local/Cellar/boost/1.72.0/lib + +The build process will run much faster if multiple processors/cores are available. To build the COMPAS executable using (e.g.) 4 cores, type:: + + make -j 4 -f Makefile BOOSTINCDIR=/usr/local/Cellar/boost/1.72.0/include BOOSTLIBDIR=/usr/local/Cellar/boost/1.72.0/lib + +Note that both ``make`` commands shown above will conduct incremental builds: they will only compile source files that have changed. To ensure a clean build +in which all source files are compiled, type:: + + make clean + make -j 4 -f Makefile BOOSTINCDIR=/usr/local/Cellar/boost/1.72.0/include BOOSTLIBDIR=/usr/local/Cellar/boost/1.72.0/lib + +The `clean` option instructs ``make`` to remove all existing object files (.o), and the COMPAS executable. A subsequent ``make`` is then forced to compile +all source files and link the resultant object files (and external libraries) into a new executable. + +Note that rather than type the ``make`` command each time you want to build COMPAS, you could create a file containing the ``make`` command, and execute that +file to build COMPAS. + +Once built, the executable can be tested with, e.g.:: + + ./COMPAS -v + +which will display the code version. + +See :doc:`../Developer guide/Developer build/COMPAS-local-build` for a detailed description of ``Makefile`` functionality. + + +:bolditalictext:`A note for Mac users:` + +If you are using MacOS and running into linking issues with the boost libraries, try:: + + make clean + make CPP=clang++ -j$(sysctl -n hw.ncpu) + +In some Mac installations, the GNU C++ compiler is not installed how we might expect, so trying to compile and link with ``clang++`` might help. + + +Installing python utilities +--------------------------- + +You can use pip to install the `compas_python_utils` + +:: + + pip install . + + +Use `-e .[dev]` to install in development mode (i.e. editable mode) and include the development dependencies. + +:: + + pip install -e .[dev] + + + +Next steps +---------- Once you have completed the steps shown above, you're ready to run COMPAS. The :doc:`COMPAS User Guide <../User guide/user-guide>` explains in detail how to run COMPAS, but to check that COMPAS is installed correctly, and to get a taste of what running COMPAS looks -like, you could try the :doc:`COMPAS Tutorial <../User guide/Tutorial/example-compas-run>`. +like, you could try the :doc:`COMPAS Tutorial <../User guide/Running COMPAS/running-compas>`. diff --git a/online-docs/pages/Getting started/git-details.rst b/online-docs/pages/Getting started/git-details.rst deleted file mode 100644 index 6924bc2ff..000000000 --- a/online-docs/pages/Getting started/git-details.rst +++ /dev/null @@ -1,89 +0,0 @@ -COMPAS code repository -====================== - -The public COMPAS code resides in a ``GitHub``\ [#f1]_ repository. You will need access to ``GitHub``, and the ``git`` version -control system installed. - -If you do not have ``git`` installed, visit `Install Git `__ and follow the instructions there. - - -Getting your first copy of the COMPAS source code -------------------------------------------------- - -While you don't need a ``GitHub`` account to read the COMPAS ``GitHub`` repository, you will need an account to push your code -changes to the repository. If you plan to contribute to the COMPAS code base, you will need to create a ``GitHub`` account. - - -To Fork or Not to Fork? ------------------------ - -You can clone the COMPAS repository directly, or first create a fork of the repository and clone the fork. - -Forking a ``GitHub`` repository creates a copy of the repository on ``GitHub``, in your account. The original repository, and the fork -created, are linked on ``GitHub``. - -Cloning a repository creates a copy of the repository on your local system. - -See `The difference between forking and cloning a repository `__ -to learn more about the pros and cons of forking a ``GitHub`` repository. - - -If you choose to fork the COMPAS repository, use the “fork” button at the top right of the ``GitHub`` repository page. - - -Creating a clone of the GitHub repository ------------------------------------------ - -Whether you forked the COMPAS repository or chose to work directly with the repository, you will need to clone (copy) the repository to -your local system. - -First, change to the directory on your local system within which you wish to store your local copy of the COMPAS source code -(throughout this documentation we use the example directory `~/codes`): - -:: - - cd ~/codes - - -If you have configured your ``GitHub`` account for ``SSH``, you can clone with: - -:: - - git clone git@github.com:USERNAME/REPONAME.git - - -If you have not yet configured your ``GitHub`` account with ``SSH``, you can clone over ``HTTPS``: - -:: - - git clone https://github.com/USERNAME/REPONAME.git - - -(Subsititute your GitHub username for "USERNAME", and the GitHub repository name for "REPONAME" -("COMPAS" if you did not create a fork)) - -At the completion of the command you will have a copy (clone) of the COMPAS ``GitHub`` repository in the `~/codes` directory on your -local system. - -You can also use the green "Code" dropdown on the ``GitHub`` repository page to clone the repository. - - - -Setting your username and email address ---------------------------------------- - -Before you can push changes, you must ensure that your name and email address are set: - -:: - - cd ~/codes - git config --global user.name "Fred Nurk" - git config --global user.email "fred.nurk@aplace.adomain" - - -You should now be ready to start using COMPAS! - - -.. rubric:: Footnotes - -.. [#f1] https://github.com/ diff --git a/online-docs/pages/User guide/Post-processing/CHE_paper_tutorial/CHE_evolution_demo_ANSWERS.ipynb b/online-docs/pages/User guide/Post-processing/CHE_paper_tutorial/CHE_evolution_demo_ANSWERS.ipynb index 74190ff88..1a9ad0836 100644 --- a/online-docs/pages/User guide/Post-processing/CHE_paper_tutorial/CHE_evolution_demo_ANSWERS.ipynb +++ b/online-docs/pages/User guide/Post-processing/CHE_paper_tutorial/CHE_evolution_demo_ANSWERS.ipynb @@ -1548,7 +1548,7 @@ "\n", "## Compact Object Mergers: Population Astrophysics & Statistics\n", "\n", - "[![Documentation](https://img.shields.io/badge/Documentation-latest-orange.svg?style=flat)](https://github.com/TeamCOMPAS/COMPAS/blob/Documentation/COMPAS_Documentation.pdf)\n", + "[![Documentation](https://img.shields.io/badge/Documentation-latest-orange.svg?style=flat)](https://github.com/TeamCOMPAS/COMPAS/)\n", "\n", "[//]: ## (Outline features)\n", "COMPAS is a publicly available rapid binary population synthesis code (https://compas.science/) that is designed so that evolution prescriptions and model parameters are easily \n", diff --git a/online-docs/pages/User guide/Post-processing/post-processing.rst b/online-docs/pages/User guide/Post-processing/post-processing.rst index 716f78895..973c84ac4 100644 --- a/online-docs/pages/User guide/Post-processing/post-processing.rst +++ b/online-docs/pages/User guide/Post-processing/post-processing.rst @@ -28,8 +28,9 @@ Post-processing Demos Cosmic Integration Spin prescriptions CHE Tutorial + CHE Tutorial (no answers) .. rubric:: Footnotes -.. [#f1] https://www.hdfgroup.org/ \ No newline at end of file +.. [#f1] https://www.hdfgroup.org/ diff --git a/online-docs/pages/User guide/Pre-processing/pre-processing-runSubmit.rst b/online-docs/pages/User guide/Pre-processing/pre-processing-runSubmit.rst deleted file mode 100644 index 994e4d623..000000000 --- a/online-docs/pages/User guide/Pre-processing/pre-processing-runSubmit.rst +++ /dev/null @@ -1,9 +0,0 @@ -runSubmit.py -============ - -runSubmit.py is a Python script that, in conjunction with a :doc:`YAML file<./pre-processing-yaml>`, constructs and -executes the operating system command that runs COMPAS. This is a convenient method of running COMPAS when the number -of COMPAS options to be specified is large, or for users that are not familiar with operating system command-line -arguments. - -Refer to :doc:`Running COMPAS via Python<../Running COMPAS/running-via-python>` for more details. diff --git a/online-docs/pages/User guide/Pre-processing/pre-processing-sampling.rst b/online-docs/pages/User guide/Pre-processing/pre-processing-sampling.rst deleted file mode 100644 index 98339c981..000000000 --- a/online-docs/pages/User guide/Pre-processing/pre-processing-sampling.rst +++ /dev/null @@ -1,16 +0,0 @@ -Sampling in COMPAS -================== - -COMPAS has built-in functionality for sampling using simple distributions for initial masses, -binary mass ratios, semi-major axes, eccentricities, and metallicities. - -More complex distributions can be sampled with external scripts which can then generate -a suitable gridfile. An example is the Moe & DiStefano (2017) distribution for -the initial parameters of a binary that couples the two masses, orbital period, and eccentricity. - -The sampler script for the Moe & DiStefano (2017) distribution -can be found in ``compas_python_utils/preprocessing/sampleMoeDiStefano.py``. As described in the -header, only the number of systems and upper and lower mass bounds can be -set (the parameter correlations break if you try to set the other bounds). -These values are set at the bottom of the script. - diff --git a/online-docs/pages/User guide/Pre-processing/pre-processing.rst b/online-docs/pages/User guide/Pre-processing/pre-processing.rst deleted file mode 100644 index fd411810d..000000000 --- a/online-docs/pages/User guide/Pre-processing/pre-processing.rst +++ /dev/null @@ -1,12 +0,0 @@ -Pre-processing tools -==================== - -The COMPAS suite includes some useful pre-processing tools that are located in the `utils/pre-Processing` directory. - - -.. toctree:: - :maxdepth: 1 - - runSubmit.py: Running COMPAS via Python - COMPAS options configuration (YAML) file - Sampling tools diff --git a/online-docs/pages/User guide/Program options/program-options-list-defaults.rst b/online-docs/pages/User guide/Program options/program-options-list-defaults.rst index 5a380bd6d..ccbe64604 100644 --- a/online-docs/pages/User guide/Program options/program-options-list-defaults.rst +++ b/online-docs/pages/User guide/Program options/program-options-list-defaults.rst @@ -5,7 +5,7 @@ Any program options that are not specified take default values. - On the command line, program options that are not explicitly specified default to the COMPAS default value for the option (as specified in the COMPAS code - may be sampled from a distribution). -- On a :doc:`grid file <../grid-files>` line, program options that are not explicitly specified default to the value specified for that option on the command line. If the program option was not explicitly specified on the command line, it will default to the COMPAS default value for the option, as described above. That is, the value for any option not specified on a grid file line option falls back to the value specified on the command line, which falls back to the COMPAS default if it was not specified on the command line. +- On a :doc:`grid file <../Running COMPAS/running-grid>` line, program options that are not explicitly specified default to the value specified for that option on the command line. If the program option was not explicitly specified on the command line, it will default to the COMPAS default value for the option, as described above. That is, the value for any option not specified on a grid file line option falls back to the value specified on the command line, which falls back to the COMPAS default if it was not specified on the command line. .. _options-props-top: @@ -462,7 +462,7 @@ Default = 5.75 :ref:`Back to Top ` **--grid** |br| -Grid filename. (See :doc:`Grid files <../grid-files>`) |br| +Grid filename. (See :doc:`grid file <../Running COMPAS/running-grid>`) |br| Default = ’’ (None) **--grid-lines-to-process** |br| diff --git a/online-docs/pages/User guide/Program options/program-options-mixing-ranges-sets.rst b/online-docs/pages/User guide/Program options/program-options-mixing-ranges-sets.rst index 2ad3accaf..78c92f129 100644 --- a/online-docs/pages/User guide/Program options/program-options-mixing-ranges-sets.rst +++ b/online-docs/pages/User guide/Program options/program-options-mixing-ranges-sets.rst @@ -2,7 +2,7 @@ Mixing ranges and sets ====================== Ranges and sets can be specified together, and there is no limit to the number of ranges or sets that can be -specified on the command line, or in the :doc:`grid file <../grid-files>`. +specified on the command line, or in the :doc:`grid file <../Running COMPAS/running-grid>`. Running COMPAS with the command:: diff --git a/online-docs/pages/User guide/Program options/program-options.rst b/online-docs/pages/User guide/Program options/program-options.rst index 2a0c5ac69..0258502c1 100644 --- a/online-docs/pages/User guide/Program options/program-options.rst +++ b/online-docs/pages/User guide/Program options/program-options.rst @@ -6,7 +6,7 @@ parameters that affect the evolution of single and binary stars, and the composi stars being evolved. Furthermore, COMPAS allows some parameters to be specified as ranges, or sets, of values via the program options, allowing users to specify a grid of parameter values on the command line. -Combining command-line program options ranges and sets with a :doc:`grid file <../grid-files>` allows users +Combining command-line program options ranges and sets with a :doc:`grid file <../Running COMPAS/running-grid>` allows users more flexibility and the ability to specify more complex combinations of parameter values. Not all program options can be specified as ranges or sets of values. Options for which mixing different diff --git a/online-docs/pages/User guide/Running COMPAS/example/COMPAS_Output/Run_Details b/online-docs/pages/User guide/Running COMPAS/example/COMPAS_Output/Run_Details new file mode 100644 index 000000000..e11488f7b --- /dev/null +++ b/online-docs/pages/User guide/Running COMPAS/example/COMPAS_Output/Run_Details @@ -0,0 +1,238 @@ + +COMPAS v02.38.04 +Compact Object Mergers: Population Astrophysics and Statistics +by Team COMPAS (http://compas.science/index.html) +A binary star simulator + +Start generating binaries at Thu Sep 5 14:51:57 2024 + +Generated 4 of 4 binaries requested + +End generating binaries at Thu Sep 5 14:51:58 2024 + +Clock time = 0.175891 CPU seconds +Wall time = 0000:00:00 (hhhh:mm:ss) + + +COMMAND LINE OPTIONS +-------------------- + +PISN-lower-limit = 60.000000, DEFAULT_USED, DOUBLE +PISN-upper-limit = 135.000000, DEFAULT_USED, DOUBLE +PPI-lower-limit = 35.000000, DEFAULT_USED, DOUBLE +PPI-upper-limit = 60.000000, DEFAULT_USED, DOUBLE +YAML-template = '', DEFAULT_USED, STRING +add-options-to-sysparms = 'GRID', DEFAULT_USED, STRING +allow-non-stripped-ECSN = FALSE, DEFAULT_USED, BOOL +allow-rlof-at-birth = TRUE, DEFAULT_USED, BOOL +allow-touching-at-birth = FALSE, DEFAULT_USED, BOOL +angular-momentum-conservation-during-circularisation = FALSE, DEFAULT_USED, BOOL +black-hole-kicks = 'FALLBACK', DEFAULT_USED, STRING +case-BB-stability-prescription = 'ALWAYS_STABLE', DEFAULT_USED, STRING +check-photon-tiring-limit = FALSE, DEFAULT_USED, BOOL +chemically-homogeneous-evolution = 'PESSIMISTIC', DEFAULT_USED, STRING +circularise-binary-during-mass-transfer = TRUE, DEFAULT_USED, BOOL +common-envelope-allow-immediate-RLOF-post-CE-survive = FALSE, DEFAULT_USED, BOOL +common-envelope-allow-main-sequence-survive = TRUE, DEFAULT_USED, BOOL +common-envelope-allow-radiative-envelope-survive = FALSE, DEFAULT_USED, BOOL +common-envelope-alpha = 1.000000, DEFAULT_USED, DOUBLE +common-envelope-alpha-thermal = 1.000000, DEFAULT_USED, DOUBLE +common-envelope-formalism = 'ENERGY', DEFAULT_USED, STRING +common-envelope-lambda = 0.100000, DEFAULT_USED, DOUBLE +common-envelope-lambda-multiplier = 1.000000, DEFAULT_USED, DOUBLE +common-envelope-lambda-nanjing-enhanced = FALSE, DEFAULT_USED, BOOL +common-envelope-lambda-nanjing-interpolate-in-mass = FALSE, DEFAULT_USED, BOOL +common-envelope-lambda-nanjing-interpolate-in-metallicity = FALSE, DEFAULT_USED, BOOL +common-envelope-lambda-nanjing-use-rejuvenated-mass = FALSE, DEFAULT_USED, BOOL +common-envelope-lambda-prescription = 'LAMBDA_NANJING', DEFAULT_USED, STRING +common-envelope-mass-accretion-constant = 0.000000, DEFAULT_USED, DOUBLE +common-envelope-mass-accretion-max = 0.100000, DEFAULT_USED, DOUBLE +common-envelope-mass-accretion-min = 0.040000, DEFAULT_USED, DOUBLE +common-envelope-mass-accretion-prescription = 'ZERO', DEFAULT_USED, STRING +common-envelope-recombination-energy-density = 15000000000000.000000, DEFAULT_USED, DOUBLE +common-envelope-slope-kruckow = -0.833333, DEFAULT_USED, DOUBLE +convective-envelope-temperature-threshold = 5370.000000, DEFAULT_USED, DOUBLE +cool-wind-mass-loss-multiplier = 1.000000, DEFAULT_USED, DOUBLE +create-YAML-file = '', DEFAULT_USED, STRING +critical-mass-ratio-HG-degenerate-accretor = 0.210000, DEFAULT_USED, DOUBLE +critical-mass-ratio-HG-non-degenerate-accretor = 0.250000, DEFAULT_USED, DOUBLE +critical-mass-ratio-MS-high-mass-degenerate-accretor = 0.000000, DEFAULT_USED, DOUBLE +critical-mass-ratio-MS-high-mass-non-degenerate-accretor = 0.625000, DEFAULT_USED, DOUBLE +critical-mass-ratio-MS-low-mass-degenerate-accretor = 1.000000, DEFAULT_USED, DOUBLE +critical-mass-ratio-MS-low-mass-non-degenerate-accretor = 1.440000, DEFAULT_USED, DOUBLE +critical-mass-ratio-giant-degenerate-accretor = 0.870000, DEFAULT_USED, DOUBLE +critical-mass-ratio-giant-non-degenerate-accretor = -1.000000, DEFAULT_USED, DOUBLE +critical-mass-ratio-helium-HG-degenerate-accretor = 0.210000, DEFAULT_USED, DOUBLE +critical-mass-ratio-helium-HG-non-degenerate-accretor = 0.250000, DEFAULT_USED, DOUBLE +critical-mass-ratio-helium-MS-degenerate-accretor = 0.000000, DEFAULT_USED, DOUBLE +critical-mass-ratio-helium-MS-non-degenerate-accretor = 0.000000, DEFAULT_USED, DOUBLE +critical-mass-ratio-helium-giant-degenerate-accretor = 0.870000, DEFAULT_USED, DOUBLE +critical-mass-ratio-helium-giant-non-degenerate-accretor = 1.280000, DEFAULT_USED, DOUBLE +critical-mass-ratio-prescription = 'NONE', DEFAULT_USED, STRING +critical-mass-ratio-white-dwarf-degenerate-accretor = 1.600000, DEFAULT_USED, DOUBLE +critical-mass-ratio-white-dwarf-non-degenerate-accretor = 0.000000, DEFAULT_USED, DOUBLE +debug-classes = { }, DEFAULT_USED, VECTOR +debug-level = 0, DEFAULT_USED, SIGNED +debug-to-file = FALSE, DEFAULT_USED, BOOL +detailed-output = FALSE, DEFAULT_USED, BOOL +eccentricity = 0.000000, DEFAULT_USED, DOUBLE +eccentricity-distribution = 'ZERO', DEFAULT_USED, STRING +eccentricity-max = 1.000000, DEFAULT_USED, DOUBLE +eccentricity-min = 0.000000, DEFAULT_USED, DOUBLE +eddington-accretion-factor = 1.000000, DEFAULT_USED, DOUBLE +enable-warnings = FALSE, DEFAULT_USED, BOOL +envelope-state-prescription = 'LEGACY', DEFAULT_USED, STRING +errors-to-file = FALSE, DEFAULT_USED, BOOL +evolve-pulsars = FALSE, DEFAULT_USED, BOOL +evolve-unbound-systems = TRUE, DEFAULT_USED, BOOL +expel-convective-envelope-above-luminosity-threshold = FALSE, DEFAULT_USED, BOOL +fix-dimensionless-kick-magnitude = -1.000000, DEFAULT_USED, DOUBLE +fryer-22-fmix = 0.500000, DEFAULT_USED, DOUBLE +fryer-22-mcrit = 5.750000, DEFAULT_USED, DOUBLE +fryer-supernova-engine = 'DELAYED', DEFAULT_USED, STRING +grid = 'grid_demo.txt', USER_SUPPLIED, STRING +grid-lines-to-process = 9223372036854775807, DEFAULT_USED, LONG +grid-start-line = 0, DEFAULT_USED, LONG +hdf5-buffer-size = 1, DEFAULT_USED, SIGNED +hdf5-chunk-size = 100000, DEFAULT_USED, SIGNED +help = FALSE, DEFAULT_USED, BOOL +hmxr-binaries = FALSE, DEFAULT_USED, BOOL +initial-mass = 5.000000, DEFAULT_USED, DOUBLE +initial-mass-1 = 5.000000, DEFAULT_USED, DOUBLE +initial-mass-2 = 5.000000, DEFAULT_USED, DOUBLE +initial-mass-function = 'KROUPA', DEFAULT_USED, STRING +initial-mass-max = 150.000000, DEFAULT_USED, DOUBLE +initial-mass-min = 5.000000, DEFAULT_USED, DOUBLE +initial-mass-power = 0.000000, DEFAULT_USED, DOUBLE +kick-direction = 'ISOTROPIC', DEFAULT_USED, STRING +kick-direction-power = 0.000000, DEFAULT_USED, DOUBLE +kick-magnitude = 0.000000, DEFAULT_USED, DOUBLE +kick-magnitude-1 = 0.000000, DEFAULT_USED, DOUBLE +kick-magnitude-2 = 0.000000, DEFAULT_USED, DOUBLE +kick-magnitude-distribution = 'MULLERMANDEL', DEFAULT_USED, STRING +kick-magnitude-max = -1.000000, DEFAULT_USED, DOUBLE +kick-magnitude-random = 0.000000, DEFAULT_USED, DOUBLE +kick-magnitude-random-1 = 0.000000, DEFAULT_USED, DOUBLE +kick-magnitude-random-2 = 0.000000, DEFAULT_USED, DOUBLE +kick-magnitude-sigma-CCSN-BH = 265.000000, DEFAULT_USED, DOUBLE +kick-magnitude-sigma-CCSN-NS = 265.000000, DEFAULT_USED, DOUBLE +kick-magnitude-sigma-ECSN = 30.000000, DEFAULT_USED, DOUBLE +kick-magnitude-sigma-USSN = 30.000000, DEFAULT_USED, DOUBLE +kick-mean-anomaly-1 = 0.000000, DEFAULT_USED, DOUBLE +kick-mean-anomaly-2 = 0.000000, DEFAULT_USED, DOUBLE +kick-phi-1 = 0.000000, DEFAULT_USED, DOUBLE +kick-phi-2 = 0.000000, DEFAULT_USED, DOUBLE +kick-scaling-factor = 1.000000, DEFAULT_USED, DOUBLE +kick-theta-1 = 0.000000, DEFAULT_USED, DOUBLE +kick-theta-2 = 0.000000, DEFAULT_USED, DOUBLE +log-classes = { }, DEFAULT_USED, VECTOR +log-level = 0, DEFAULT_USED, SIGNED +logfile-common-envelopes = 'BSE_Common_Envelopes', DEFAULT_USED, STRING +logfile-common-envelopes-record-types = -1, DEFAULT_USED, SIGNED +logfile-definitions = '', DEFAULT_USED, STRING +logfile-detailed-output = 'BSE_Detailed_Output', DEFAULT_USED, STRING +logfile-detailed-output-record-types = -1, DEFAULT_USED, SIGNED +logfile-double-compact-objects = 'BSE_Double_Compact_Objects', DEFAULT_USED, STRING +logfile-double-compact-objects-record-types = -1, DEFAULT_USED, SIGNED +logfile-name-prefix = '', DEFAULT_USED, STRING +logfile-pulsar-evolution = 'BSE_Pulsar_Evolution', DEFAULT_USED, STRING +logfile-pulsar-evolution-record-types = -1, DEFAULT_USED, SIGNED +logfile-rlof-parameters = 'BSE_RLOF', DEFAULT_USED, STRING +logfile-rlof-parameters-record-types = -1, DEFAULT_USED, SIGNED +logfile-supernovae = 'BSE_Supernovae', DEFAULT_USED, STRING +logfile-supernovae-record-types = -1, DEFAULT_USED, SIGNED +logfile-switch-log = 'BSE_Switch_Log', DEFAULT_USED, STRING +logfile-system-parameters = 'BSE_System_Parameters', DEFAULT_USED, STRING +logfile-system-parameters-record-types = -1, DEFAULT_USED, SIGNED +logfile-type = 'HDF5', DEFAULT_USED, STRING +luminosity-to-mass-threshold = 4.200000, DEFAULT_USED, DOUBLE +luminous-blue-variable-multiplier = 1.500000, DEFAULT_USED, DOUBLE +luminous-blue-variable-prescription = 'HURLEY_ADD', DEFAULT_USED, STRING +mass-loss-prescription = 'VINK', DEFAULT_USED, STRING +mass-ratio = 1.000000, DEFAULT_USED, DOUBLE +mass-ratio-distribution = 'FLAT', DEFAULT_USED, STRING +mass-ratio-max = 1.000000, DEFAULT_USED, DOUBLE +mass-ratio-min = 0.010000, DEFAULT_USED, DOUBLE +mass-transfer = TRUE, DEFAULT_USED, BOOL +mass-transfer-accretion-efficiency-prescription = 'THERMAL', DEFAULT_USED, STRING +mass-transfer-angular-momentum-loss-prescription = 'ISOTROPIC', DEFAULT_USED, STRING +mass-transfer-fa = 0.500000, DEFAULT_USED, DOUBLE +mass-transfer-jloss = 1.000000, DEFAULT_USED, DOUBLE +mass-transfer-jloss-macleod-linear-fraction = 0.500000, DEFAULT_USED, DOUBLE +mass-transfer-rejuvenation-prescription = 'STARTRACK', DEFAULT_USED, STRING +mass-transfer-thermal-limit-C = 10.000000, DEFAULT_USED, DOUBLE +mass-transfer-thermal-limit-accretor = 'CFACTOR', DEFAULT_USED, STRING +maximum-evolution-time = 13700.000000, DEFAULT_USED, DOUBLE +maximum-mass-donor-nandez-ivanova = 2.000000, DEFAULT_USED, DOUBLE +maximum-neutron-star-mass = 2.500000, DEFAULT_USED, DOUBLE +maximum-number-timestep-iterations = 99999, DEFAULT_USED, SIGNED +mcbur1 = 1.600000, DEFAULT_USED, DOUBLE +metallicity = 0.014200, DEFAULT_USED, DOUBLE +metallicity-distribution = 'ZSOLAR', DEFAULT_USED, STRING +metallicity-max = 0.030000, DEFAULT_USED, DOUBLE +metallicity-min = 0.000100, DEFAULT_USED, DOUBLE +minimum-secondary-mass = 0.100000, DEFAULT_USED, DOUBLE +mode = 'BSE', DEFAULT_USED, STRING +muller-mandel-kick-multiplier-BH = 200.000000, DEFAULT_USED, DOUBLE +muller-mandel-kick-multiplier-NS = 520.000000, DEFAULT_USED, DOUBLE +muller-mandel-sigma-kick = 0.300000, DEFAULT_USED, DOUBLE +neutrino-mass-loss-BH-formation = 'FIXED_MASS', DEFAULT_USED, STRING +neutrino-mass-loss-BH-formation-value = 0.100000, DEFAULT_USED, DOUBLE +neutron-star-equation-of-state = 'SSE', DEFAULT_USED, STRING +notes = { }, DEFAULT_USED, VECTOR +notes-hdrs = { }, DEFAULT_USED, VECTOR +number-of-systems = 10, DEFAULT_USED, SIGNED +orbital-period = 0.100000, DEFAULT_USED, DOUBLE +orbital-period-distribution = 'FLATINLOG', DEFAULT_USED, STRING +orbital-period-max = 1000.000000, DEFAULT_USED, DOUBLE +orbital-period-min = 1.100000, DEFAULT_USED, DOUBLE +output-container = 'COMPAS_Output', DEFAULT_USED, STRING +output-path = '.', DEFAULT_USED, STRING +overall-wind-mass-loss-multiplier = 1.000000, DEFAULT_USED, DOUBLE +pair-instability-supernovae = TRUE, DEFAULT_USED, BOOL +population-data-printing = FALSE, DEFAULT_USED, BOOL +print-bool-as-string = FALSE, DEFAULT_USED, BOOL +pulsar-birth-magnetic-field-distribution = 'ZERO', DEFAULT_USED, STRING +pulsar-birth-magnetic-field-distribution-max = 13.000000, DEFAULT_USED, DOUBLE +pulsar-birth-magnetic-field-distribution-min = 11.000000, DEFAULT_USED, DOUBLE +pulsar-birth-spin-period-distribution = 'ZERO', DEFAULT_USED, STRING +pulsar-birth-spin-period-distribution-max = 100.000000, DEFAULT_USED, DOUBLE +pulsar-birth-spin-period-distribution-min = 10.000000, DEFAULT_USED, DOUBLE +pulsar-magnetic-field-decay-massscale = 0.025000, DEFAULT_USED, DOUBLE +pulsar-magnetic-field-decay-timescale = 1000.000000, DEFAULT_USED, DOUBLE +pulsar-minimum-magnetic-field = 8.000000, DEFAULT_USED, DOUBLE +pulsational-pair-instability = TRUE, DEFAULT_USED, BOOL +pulsational-pair-instability-prescription = 'MARCHANT', DEFAULT_USED, STRING +quiet = FALSE, DEFAULT_USED, BOOL +random-seed = 0, DEFAULT_USED, UNSIGNED_LONG +remnant-mass-prescription = 'MULLERMANDEL', DEFAULT_USED, STRING +retain-core-mass-during-caseA-mass-transfer = TRUE, DEFAULT_USED, BOOL +revised-energy-formalism-nandez-ivanova = FALSE, DEFAULT_USED, BOOL +rlof-printing = TRUE, DEFAULT_USED, BOOL +rotational-frequency = 0.000000, DEFAULT_USED, DOUBLE +rotational-frequency-1 = 0.000000, DEFAULT_USED, DOUBLE +rotational-frequency-2 = 0.000000, DEFAULT_USED, DOUBLE +rotational-velocity-distribution = 'ZERO', DEFAULT_USED, STRING +semi-major-axis = 0.100000, DEFAULT_USED, DOUBLE +semi-major-axis-distribution = 'FLATINLOG', DEFAULT_USED, STRING +semi-major-axis-max = 1000.000000, DEFAULT_USED, DOUBLE +semi-major-axis-min = 0.010000, DEFAULT_USED, DOUBLE +stellar-zeta-prescription = 'SOBERMAN', DEFAULT_USED, STRING +store-input-files = TRUE, DEFAULT_USED, BOOL +switch-log = FALSE, DEFAULT_USED, BOOL +timestep-multiplier = 1.000000, DEFAULT_USED, DOUBLE +use-mass-loss = TRUE, DEFAULT_USED, BOOL +version = FALSE, DEFAULT_USED, BOOL +wolf-rayet-multiplier = 0.100000, DEFAULT_USED, DOUBLE +zeta-adiabatic-arbitrary = 10000.000000, DEFAULT_USED, DOUBLE +zeta-main-sequence = 2.000000, DEFAULT_USED, DOUBLE +zeta-radiative-envelope-giant = 6.500000, DEFAULT_USED, DOUBLE + + +OTHER PARAMETERS +---------------- + +useFixedUK = FALSE, CALCULATED, BOOL +actual-output-path = /Users/avaj0001/Documents/projects/compas_dev/COMPAS/online-docs/pages/User guide/Running COMPAS/example, CALCULATED, STRING +fixedRandomSeed = FALSE, CALCULATED, BOOL +Actual random seed = 1725504717, CALCULATED, UNSIGNED_LONG diff --git a/online-docs/pages/User guide/Running COMPAS/example/grid_demo.txt b/online-docs/pages/User guide/Running COMPAS/example/grid_demo.txt new file mode 100644 index 000000000..b1cb79f98 --- /dev/null +++ b/online-docs/pages/User guide/Running COMPAS/example/grid_demo.txt @@ -0,0 +1,4 @@ +--initial-mass-1 35 --initial-mass-2 31 -a 3.5 --metallicity 0.001 +--initial-mass-1 31 --initial-mass-2 31 -a 3.5 --metallicity 0.001 +--initial-mass-1 40 --initial-mass-2 31 -a 3.5 --metallicity 0.001 +--initial-mass-1 35 --initial-mass-2 25 -a 3.5 --metallicity 0.001 \ No newline at end of file diff --git a/online-docs/pages/User guide/Running COMPAS/running-compas.rst b/online-docs/pages/User guide/Running COMPAS/running-compas.rst index 46715c4fc..086a837f1 100644 --- a/online-docs/pages/User guide/Running COMPAS/running-compas.rst +++ b/online-docs/pages/User guide/Running COMPAS/running-compas.rst @@ -10,4 +10,6 @@ There are several ways to run COMPAS: each method suiting different needs: running-via-cmdline running-via-python running-via-docker + running-detailed-output + running-grid diff --git a/online-docs/pages/User guide/Tutorial/example-compas-run-detailed-output.rst b/online-docs/pages/User guide/Running COMPAS/running-detailed-output.rst similarity index 96% rename from online-docs/pages/User guide/Tutorial/example-compas-run-detailed-output.rst rename to online-docs/pages/User guide/Running COMPAS/running-detailed-output.rst index 05eed8fbf..5a8c5318a 100644 --- a/online-docs/pages/User guide/Tutorial/example-compas-run-detailed-output.rst +++ b/online-docs/pages/User guide/Running COMPAS/running-detailed-output.rst @@ -1,4 +1,4 @@ -Examining detailed output +Running detailed output ========================= The COMPAS run from the tutorial creates a new directory ``COMPAS_Output``, inside which you will find the following files/directories diff --git a/online-docs/pages/User guide/grid-files.rst b/online-docs/pages/User guide/Running COMPAS/running-grid.rst similarity index 83% rename from online-docs/pages/User guide/grid-files.rst rename to online-docs/pages/User guide/Running COMPAS/running-grid.rst index c9996ff4a..450f4e720 100644 --- a/online-docs/pages/User guide/grid-files.rst +++ b/online-docs/pages/User guide/Running COMPAS/running-grid.rst @@ -1,11 +1,11 @@ -Grid files -========== +Running COMPAS using a grid file +================================ -A grid file allows users to specify initial values for multiple systems for both Single Star Evolution (SSE) and Binary Star Evolution -(BSE). Each line of a grid file is used by COMPAS to set the initial conditions and evolutionary parameters for an individual single +A grid file allows users to specify initial values for multiple systems for both Single Star Evolution (SSE) and Binary Star Evolution +(BSE). Each line of a grid file is used by COMPAS to set the initial conditions and evolutionary parameters for an individual single star (SSE) or binary star (BSE), and each single star or binary star defined by a grid file line is evolved using those values. -Each line of a grid file is a set of program option specifications, with the specifications being exactly as they would appear on the +Each line of a grid file is a set of program option specifications, with the specifications being exactly as they would appear on the command line if running COMPAS from the command line. For example, a grid file could contain the following two lines: @@ -15,11 +15,11 @@ For example, a grid file could contain the following two lines: in which case COMPAS would evolve two binaries, with the option values set per the grid file lines. -Grid files can have blank lines and comments. Comments begin with a hash/pound character ('#') - the hash/pound character and text +Grid files can have blank lines and comments. Comments begin with a hash/pound character ('#') - the hash/pound character and text beyond it are ignored by COMPAS. Not all program options can be specified in a grid file. Options that should remain constant for a single execution of COMPAS, such as -options that specify the mode of evolution (e.g. ``--mode``), or the name or path of output files (e.g. ``--output-path``, +options that specify the mode of evolution (e.g. ``--mode``), or the name or path of output files (e.g. ``--output-path``, ``--logfile-detailed-output`` etc.) can only be specified on the command line. COMPAS will issue an error message if an option that is not supported in a grid file is specified on a grid file line. @@ -32,16 +32,37 @@ Specifying a Subset of the Grid File to be Processed Users can instruct COMPAS to process only a subset of a specified grid file. This is achieved via the program options ``--grid-start-line``, and ``--grid-lines-to-process``: - The ``--grid-start-line`` program option takes a single parameter: an integer specifying the zero-based line number of the first line of - the grid file to be processed. The default value is 0 - the first line of the grid file. Specifying a start line beyond the end of the + The ``--grid-start-line`` program option takes a single parameter: an integer specifying the zero-based line number of the first line of + the grid file to be processed. The default value is 0 - the first line of the grid file. Specifying a start line beyond the end of the grid file will result in an UNEXPECTED-END-OF-FILE error. - The ``--grid-lines-to-process`` program option takes a single parameter: an integer specifying the number of lines of the grid file to be - processed. The default is to process all lines in the grid file from the start line (which may have been specified by the - ``--grid-start-line option``) through to the end of the grid file. Specifying a number of lines to be processed that, when coupled with + The ``--grid-lines-to-process`` program option takes a single parameter: an integer specifying the number of lines of the grid file to be + processed. The default is to process all lines in the grid file from the start line (which may have been specified by the + ``--grid-start-line option``) through to the end of the grid file. Specifying a number of lines to be processed that, when coupled with the start line, would result in attempting to process lines beyond the end of the grid file will result in an INCOMPLETE-GRID error. - + Note that blank lines and comments count towards the number of grid lines processed by COMPAS when deciding if the number specified by the user has been reached. Both option ``--grid-start-line`` and ``--grid-lines-to-process`` are ignored if no grid file is specified via the ``--grid`` program option. + + + +Example +~~~~~~~ + +We will submit a set of COMPAS runs using a grid-file ``grid_demo.txt'' +.. code-block:: + + COMPAS --grid grid_demo.txt + +Contents of ``grid_demo.txt``:: + +.. include:: example/grid_demo.txt + + + +Output: + +.. include:: example/COMPAS_Output/Run_Details + diff --git a/online-docs/pages/User guide/Running COMPAS/running-via-cmdline.rst b/online-docs/pages/User guide/Running COMPAS/running-via-cmdline.rst index e3f496e59..e136ef11a 100644 --- a/online-docs/pages/User guide/Running COMPAS/running-via-cmdline.rst +++ b/online-docs/pages/User guide/Running COMPAS/running-via-cmdline.rst @@ -3,7 +3,7 @@ Running COMPAS from the command line COMPAS is a command-line application. Interaction with COMPAS is entirely through the terminal and shell - there is no visual or graphical user interface (GUI). COMPAS interacts with the user by accepting input via the keyboard, and providing -output by writing plain text to the terminal. COMPAS reads input files where necessary: a ``grid`` file (see :doc:`../grid-files`), +output by writing plain text to the terminal. COMPAS reads input files where necessary: a ``grid`` file (see :doc:`running-grid`), and a log file definitions file (see :doc:`../COMPAS output/standard-logfiles-record-specification`), and produces output files (see :doc:`../COMPAS output/output`), but these are not interactive. diff --git a/online-docs/pages/User guide/Tutorial/example-compas-run-grid.rst b/online-docs/pages/User guide/Tutorial/example-compas-run-grid.rst deleted file mode 100644 index b8181a0eb..000000000 --- a/online-docs/pages/User guide/Tutorial/example-compas-run-grid.rst +++ /dev/null @@ -1,76 +0,0 @@ -Running COMPAS using a grid file -================================ - -In population synthesis, the initial stellar population is usually generated by drawing the primary mass, secondary mass, semi-major axis, -and eccentricity from their respective distributions specified in the program options. However, we illustrate COMPAS's ability to specify -a grid of initial values for single and binary star evolution using COMPAS's grid functionality. - -An example grid file, ``Grid_demo.txt``, is included in the ``detailed_evolution`` directory. Open it with a text editor to view it:: - - # Demo BSE Grid file - - --initial-mass-1 35.4 --initial-mass-2 29.3 --metallicity 0.001 --eccentricity 0.000000e+00 --semi-major-axis 1.02 - -It should be clear that this grid file specifies a binary of zero-age main sequence stars with primary mass -35.4\ :math:`\small M_\odot`, secondary mass 29.3\ :math:`\small M_\odot`, metallicity 0.001, zero eccentricity, and semi-major axis of -1.02AU. See :doc:`../grid-files` for detailed information regarding COMPAS's grid functionality for both single and binary stars. - -We will execute COMPAS via the ``runSubmit.py`` script, but first we need to edit the companion ``compasConfigDefault.yaml`` script to instruct COMPAS to read the grid file -(via the ``grid`` program option). - -Open ``$COMPAS_ROOT_DIR/preProcessing/compasConfigDefault.yaml`` with a text editor, and specify the grid filename:: - - grid_filename = 'Grid_demo.txt' - -Note the quotes around the filename. - -If the filename specified is not fully-qualified, and the shell environment variable ``COMPAS_INPUT_DIR_PATH`` exists and is not empty, -the value of ``COMPAS_INPUT_DIR_PATH`` will be prepended to the specified grid filename. - - -To print the detailed evolution of binary properties over time, we need to turn on detailed output, by specifying:: - - detailed_output = True - -in ``compasConfigDefault.yaml``. - -COMPAS can produce logfiles of different types: ``HDF5``, ``CSV``, ``TSV``, and ``TXT``, which can be chosen by editing the line:: - - logfile_type = 'HDF5' - -in ``compasConfigDefault.yaml``. The default type is ``HDF5`` - we'll leave the default. - -NOTE: we are currently updating our documentation and will include a ``compasConfigDefault.yaml`` for the demo asap. - -.. - For this tutorial, this has all been done for you in the file ``pythonSubmitDemo.py`` found in the ``examples/methods_paper_plots/detailed_evolution/`` directory. - -.. - Now let's run COMPAS! - -.. - :: - - $ python3 pythonSubmitDemo.py - - COMPAS v02.18.06 - Compact Object Mergers: Population Astrophysics and Statistics - by Team COMPAS (http://compas.science/index.html) - A binary star simulator - - Start generating binaries at Thu Feb 25 14:42:05 2021 - - Evolution of current binary stopped: Double compact object - 0: Evolution stopped: (Main_Sequence_>_0.7 -> Black_Hole) + (Main_Sequence_>_0.7 -> Black_Hole) - - Generated 1 of 1 binaries requested - - Simulation completed - - End generating binaries at Thu Feb 25 14:42:05 2021 - - Clock time = 0.108338 CPU seconds - Wall time = 00:00:00 (hh:mm:ss) - -.. - Congratulations! You've just made a binary black hole. And it didn't even take a second. diff --git a/online-docs/pages/User guide/Tutorial/example-compas-run.rst b/online-docs/pages/User guide/Tutorial/example-compas-run.rst deleted file mode 100644 index 5947a7bcd..000000000 --- a/online-docs/pages/User guide/Tutorial/example-compas-run.rst +++ /dev/null @@ -1,34 +0,0 @@ -Tutorial: simple COMPAS run -=========================== - -NOTE: we are currently updating our documentation and will include a ``compasConfigDefault.yaml`` for the demo asap. - -.. - This tutorial assumes that you have already built the COMPAS executable as described in :doc:`../../Getting started/building-COMPAS`. - - For this example you will need the python script ``pythonSubmitDemo.py``, which specifies all the program options (physics assumptions, - output types) and runs COMPAS in the terminal. Although the primary functionality of COMPAS is to evolve a whole population of binary - stars rapidly, for now, let's focus on evolving a single stellar system and examining the detailed output. - - If you haven't yet defined the ``COMPAS_ROOT_DIR`` environment variable, do that now:: - - export COMPAS_ROOT_DIR=path-to-compas - - where `path-to-compas` should be replaced with the path to the parent directory of the COMPAS `src` directory. Depending upon your system, - for the ``export`` command to take effect, it may be necessary to either restart your session or execute the following command:: - - source ~/.bashrc - - To start, change to the ``examples/methods_paper_plots/detailed_evolution/`` directory:: - - cd $COMPAS_ROOT_DIR/examples/methods_paper_plots/detailed_evolution/ - - where you will find the script ``pythonSubmitDemo.py`` for this demo. - - -.. toctree:: - :maxdepth: 1 - - ./example-compas-run-grid - ./example-compas-run-detailed-output - diff --git a/online-docs/pages/User guide/configuration.rst b/online-docs/pages/User guide/configuration.rst index ada310a78..a91eca16a 100644 --- a/online-docs/pages/User guide/configuration.rst +++ b/online-docs/pages/User guide/configuration.rst @@ -4,14 +4,14 @@ Configuration Run-time Configuration ---------------------- -COMPAS is configured at run-time via command-line options, referred to as "program options" in this documentation, and, optionally, +COMPAS is configured at run-time via command-line options, referred to as "program options" in this documentation, and, optionally, grid files. -Configuring COMPAS via command-line options and grid files gives users the flexibility to specify both the initial conditions and the -evolutionary parameters that define single and binary stars at birth, and the conditions under which the stars and systems evolve over +Configuring COMPAS via command-line options and grid files gives users the flexibility to specify both the initial conditions and the +evolutionary parameters that define single and binary stars at birth, and the conditions under which the stars and systems evolve over their lifetime. -COMPAS has a rich set of command-line options that can be set by the user, and these, coupled with the flexibility afforded by the +COMPAS has a rich set of command-line options that can be set by the user, and these, coupled with the flexibility afforded by the COMPAS grid file implementation, allow users to configure COMPAS over a broad range of initial conditions and evolutionary parameters. This provides users with the means to explore a broad range of physics and physical assumptions. @@ -19,9 +19,9 @@ This provides users with the means to explore a broad range of physics and physi Compile-time Configuration -------------------------- -The values of some physical constants, bounds for some initial conditions, evolutionary parameters, and physical processes, etc., are -specified in the COMPAS source file `constants.h`. While it is unlikely that these constants would need to be changed in most ordinary -COMPAS runs, the possibility exists that users may want to change some of them. Should that be the case, the user should change the +The values of some physical constants, bounds for some initial conditions, evolutionary parameters, and physical processes, etc., are +specified in the COMPAS source file `constants.h`. While it is unlikely that these constants would need to be changed in most ordinary +COMPAS runs, the possibility exists that users may want to change some of them. Should that be the case, the user should change the value(s) required in ``constants.h`` and rebuild the COMPAS executable. A makefile is provided in the source directory. -See :doc:`../Getting started/building-COMPAS` for details of how to build the COMPAS executable. +See :doc:`../Getting started/getting-started` for details of how to build the COMPAS executable. diff --git a/online-docs/pages/User guide/docker.rst b/online-docs/pages/User guide/docker.rst index 426ab1939..ca61a1f8c 100644 --- a/online-docs/pages/User guide/docker.rst +++ b/online-docs/pages/User guide/docker.rst @@ -1,358 +1,168 @@ +================= COMPAS and Docker ================= -Docker has been added to COMPAS to reduce time and effort required to -set up the COMPAS deployment environment. - -Instead of having to install and configure several libraries and tools -(e.g. python/pip, numpy, g++, boost) which can vary considerably between -operating systems and existing toolchains, users can instead opt to -install Docker and run COMPAS with a single command. - -This also gives users the ability to run COMPAS on cloud solutions like -`AWS EC2 `__ or `Google Compute -Engine `__ where hundreds of cores can -be provisioned without having to manually configure the environment. - -Docker works by creating an isolated and standalone environment known -as a `container `__. -Containers can be created or destroyed without affecting the host -machine or other containers\*. - -Containers are instances of images. An image is a pre-defined -setup/environment that is instantiated when started as a container -(containers are to images what objects are to classes). More -`here `__ -on the relationship between images and container. - -Containers are (almost) always run as a Linux environment. A major -benefit of this is the ability to run Linux applications in a Windows or -MacOS environment without having to jump through hoops or have a -diminished experience. - -Image definitions can be defined by users (e.g. Dockerfiles); there are -also standard images publicly available on `Docker -Hub `__ - -All that is required to start using COMPAS with Docker is the "Usage" -section (the "CI/CD" section is also highly recommended). -The other sections are provided for extra info. - -\* Containers can still interact with each other and the host machine -through mounted directories/files or exposed ports. - - +`Docker `__ has been integrated into COMPAS to simplify the setup of the COMPAS deployment environment. +Instead of manually installing and configuring various libraries and tools (e.g., python/pip, numpy, g++, boost) which can differ across operating systems and toolchains, users can install Docker and run COMPAS with a single command. +This also allows users to run COMPAS on cloud platforms like `AWS EC2 `__ or `Google Compute Engine `__, where hundreds of cores can be provisioned without manual environment configuration. +----- Usage +----- - -N.B. This section assumes `Docker `__ has -been installed and is running. -For Windows and MacOS users, see -`here `__. +**Note:** This section assumes `Docker `__ is installed and running. +For Windows and MacOS users, see `here `__. Installing +~~~~~~~~~~ +Retrieve the latest compiled version of COMPAS (dev branch) by running: -The latest compiled version of COMPAS (dev branch) can be retrieved by -running -``docker pull teamcompas/compas`` - -Other versions can be used by adding a version -`tag `__. -For example, COMPAS version 2.12.0 would be -``teamcompas/compas:2.12.0``. -To see all available versions, go to the TeamCOMPAS docker hub page -`here `__. - -Running +.. code-block:: bash + docker pull teamcompas/compas:latest -COMPAS can still be configured via command line arguments passed to the -COMPAS executable or via a ``runSubmit.py`` file. +To use other versions, add a version `tag `__. For example, for COMPAS version 2.12.0: -Running runSubmit.py +.. code-block:: bash + docker pull teamcompas/compas:2.12.0 -To run COMPAS via a ``runSubmit.py`` file, the command is a little -more complex. +To see all available versions, visit the TeamCOMPAS Docker Hub page `here `__. -:: - - docker run \ - --rm \ - -it \ - -v $(pwd)/compas-logs:/app/COMPAS/logs \ - -v $(pwd)/runSubmit.py:/app/starts/runSubmit.py \ - -e COMPAS_EXECUTABLE_PATH=/app/COMPAS/bin/COMPAS \ - -e COMPAS_LOGS_OUTPUT_DIR_PATH=/app/COMPAS/logs \ - teamcompas/compas \ - python3 /app/starts/runSubmit.py - -Breaking down this command: - -``docker run`` -creates a container - -``--rm`` -`Clean -up `__ -destroy the container once it finishes running the command - -``-it`` -short for `-i and --t `__ - -provides an interactive terminal - -``-v :`` -`Bind mounts `__ -mount ```` to `` -This time we not only want to get the output from COMPAS on the host -machine, we also want to supply a ``runSubmit.py`` to the container -from the host machine. - -NOTE: if you decide to execute using ``runSubmit.py``, you will need -a ``compasConfigDefault.yaml`` file in the same directory. This file -can be find in the same directory as the ``runSubmit.py``, and contains -the default COMPAS choices for stellar and binary physics. These choices -can be changed by modifying the options available in the ``compasConfigDefault.yaml`` -file. - -``-e VAR_NAME=value`` -`Environment -variables `__ -set the environment variable ``VAR_VAME`` to ``value`` +Running +~~~~~~~ -``teamcompas/compas`` -the image to run +COMPAS can be configured via command line arguments passed to the COMPAS executable or via a `runSubmit.py` file. -``python3 /app/starts/runSubmit.py`` -the command to run when the container starts +Running `runSubmit.py` +^^^^^^^^^^^^^^^^^^^^^^ -Run the COMPAS executable +To run COMPAS using a `runSubmit.py` file, use the following command: +.. code-block:: bash -To run the COMPAS executable directly (i.e. without ``runSubmit.py``) + docker run + --rm + -it + -v $(pwd)/compas-logs:/app/COMPAS/logs + -v $(pwd)/runSubmit.py:/app/starts/runSubmit.py + -e COMPAS_EXECUTABLE_PATH=/app/COMPAS/bin/COMPAS + -e COMPAS_LOGS_OUTPUT_DIR_PATH=/app/COMPAS/logs + teamcompas/compas + python3 /app/starts/runSubmit.py -:: - - docker run \ - --rm \ - -it \ - -v $(pwd)/compas-logs:/app/COMPAS/logs \ - teamcompas/compas \ - bin/COMPAS \ - --number-of-binaries=5 \ - --outputPath=/app/COMPAS/logs Breaking down this command: + - `docker run`: Creates a container. + - `--rm`: Cleans up and destroys the container once it finishes running the command. + - `-it`: Provides an interactive terminal. + - `-v :`: Mounts `` to ``. + - `-e VAR_NAME=value`: Sets the environment variable `VAR_NAME` to `value`. + - `teamcompas/compas`: The image to run. + - `python3 /app/starts/runSubmit.py`: The command to run when the container starts. -``docker run`` -creates a container - -``--rm`` -`Clean -up `__ -destroy the container once it finishes running the command - -``-it`` -short for `-i and --t `__ - -provides an interactive terminal +**Note:** If using `runSubmit.py`, ensure a `compasConfigDefault.yaml` file is in the same directory. This file contains default COMPAS choices for stellar and binary physics, which can be modified. -``-v :`` -`Bind mounts `__ -mount ```` to ```` -In this instance, make it so -``$(pwd)/compas-logs on my machine is the same as``/app/COMPAS/logs\` -inside the container +Running the COMPAS executable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``teamcompas/compas`` -the image to run +To run the COMPAS executable directly: -``bin/COMPAS`` -the command to run when the container starts +.. code-block:: bash -``--number-of-binaries`` -anything after the given start command is passed to that command, in -this case, the flag to set the number of binaries - -``--outputPath /app/COMPAS/logs`` -same as above, anything after the start command is given to that start -command, here it forces logs to go to the directory that is mapped to -the host machine - -More info on ``docker run`` -`here `__ + docker run --rm -it + -v $(pwd)/compas-logs:/app/COMPAS/logs teamcompas/compas bin/COMPAS + --number-of-binaries=5 + --outputPath=/app/COMPAS/logs -NOTE 1: -Two new environment variables have been added, both of these apply to -``runSubmit.py`` only and are non-breaking changes. +Breaking down this command: + - `docker run`: Creates a container. + - `--rm`: Cleans up and destroys the container once it finishes running the command. + - `-it`: Provides an interactive terminal. + - `-v :`: Mounts `` to ``. + - `teamcompas/compas`: The image to run. + - `bin/COMPAS`: The command to run when the container starts. + - `--number-of-binaries`: Sets the number of binaries. + - `--outputPath /app/COMPAS/logs`: Forces logs to go to the specified directory. -``COMPAS_EXECUTABLE_PATH`` is an addition to the default -``runSubmit.py`` that overrides where ``runSubmit.py`` looks for -the compiled COMPAS. -This override exists purely for ease-of-use from the command line. +More information on `docker run` can be found `here `__. -``COMPAS_LOGS_OUTPUT_DIR_PATH`` is also an addition to the default -``runSubmit.py`` that overrides where logs are placed. -The override exists because the mounted directory (option ``-v``) is -created before COMPAS runs. COMPAS sees that the directory where it's -supposed to put logs already exists, so it created a different (i.e. -non-mapped) directory to deposit logs in. + - **Note 1:** + Two new environment variables have been added for `runSubmit.py` only: + - `COMPAS_EXECUTABLE_PATH`: Overrides where `runSubmit.py` looks for the compiled COMPAS. + - `COMPAS_LOGS_OUTPUT_DIR_PATH`: Overrides where logs are placed. -NOTE 2: + - **Note 2:** + The `docker run ...` examples use the `-it` options. + For running multiple instances of COMPAS, use `detached mode `__ (`-d`). + This hides all container output. -The ``docker run ...`` examples above both use the ``-it`` options. -If you want to run multiple instances of COMPAS, I would highly -recommend using `detached -mode `__ -(``-d``) instead. -All container output will be hidden. +Example for running 4 instances of COMPAS: -An example where this would be useful is if you were running 4 -instances of COMPAS at once. -You could copy/paste the following into the terminal... +.. code-block:: bash -:: + docker run --rm -d + -v $(pwd)/compas-logs/run_0:/app/COMPAS/logs + -v $(pwd)/runSubmitMMsolar_01.py:/app/starts/runSubmit.py + teamcompas/compas python3 /app/starts/runSubmit.py - docker run --rm -d -v $(pwd)/compas-logs/run_0:/app/COMPAS/logs -v $(pwd)/runSubmitMMsolar_01.py:/app/starts/runSubmit.py teamcompas/compas python3 /app/starts/runSubmit.py & - - docker run --rm -d -v $(pwd)/compas-logs/run_1:/app/COMPAS/logs -v $(pwd)/runSubmitMMsolar_02.py:/app/starts/runSubmit.py teamcompas/compas python3 /app/starts/runSubmit.py & - - docker run --rm -d -v $(pwd)/compas-logs/run_2:/app/COMPAS/logs -v $(pwd)/runSubmitMMsolar_03.py:/app/starts/runSubmit.py teamcompas/compas python3 /app/starts/runSubmit.py & - - docker run --rm -d -v $(pwd)/compas-logs/run_3:/app/COMPAS/logs -v $(pwd)/runSubmitMMsolar_04.py:/app/starts/runSubmit.py teamcompas/compas python3 /app/starts/runSubmit.py + & docker run --rm -d + -v $(pwd)/compas-logs/run_1:/app/COMPAS/logs + -v $(pwd)/runSubmitMMsolar_02.py:/app/starts/runSubmit.py + teamcompas/compas python3 /app/starts/runSubmit.py -...which would run 4 separate instances of COMPAS, each with its own -``runSubmit.py`` file and logging directory, and all console output -suppressed. + & docker run --rm -d + -v $(pwd)/compas-logs/run_2:/app/COMPAS/logs + -v $(pwd)/runSubmitMMsolar_03.py:/app/starts/runSubmit.py + teamcompas/compas python3 /app/starts/runSubmit.py -You may want to check the console output to see how far into the run -COMPAS is. -The command for this is ``docker logs ``. -You can get the container id by running ``docker ps``. + & docker run --rm -d + -v $(pwd)/compas-logs/run_3:/app/COMPAS/logs + -v $(pwd)/runSubmitMMsolar_04.py:/app/starts/runSubmit.py + teamcompas/compas python3 /app/starts/runSubmit.py +To check the console output, use `docker logs `. Get the container id by running `docker ps`. +----- CI/CD +----- +Whenever a push is made to `TeamCOMPAS/dev `__, a continuous deployment process automatically builds a new image and deploys it to DockerHub with a `tag` corresponding to the value of `VERSION_STRING` in `constants.h`. +Expect the latest COMPAS docker image to be available 5-10 minutes after pushing/merging. -The latest version of COMPAS (dev branch) is available at -``teamcompas/compas``. -This is provided automatically by CI/CD. - -Whenever a push to -`TeamCOMPAS/dev `__ a -continuous deployment process automatically -`builds `__ -a new image and deploys it to DockerHub with a ``tag`` that corresponds -to the value of ``VERSION_STRING`` in ``constants.h``. - -At time of writing, `GitHub -Actions `__ is facilitating the -above process. While this is convenient (because it's free and well -supported) it is quite slow. I have plans to create a -`runner `__ -locally with a high core count that can be used to compile COMPAS -quickly, but haven't gotten around to it yet. - -You can realistically expect the latest COMPAS docker image to be -available 5 - 10 minutes after pushing/merging. - -The Github Actions configuration is in -``/.github/workflows/dockerhub-ci.yml``. - -Atlassian has a `good -writeup `__ -about what CI/CD is. - - +The GitHub Actions configuration is in `.github/workflows/dockerhub-ci.yml `__. +---------- Bonus Info - +---------- Dockerfile +^^^^^^^^^^ +The `Dockerfile `__ defines how the docker image is constructed. -The `Dockerfile `__ -defines how the docker image is constructed. - -Images are created as a combination of layers. -During the build process each layer is cached and only updated on -subsequent builds if that layer would change. - -The Dockerfile for COMPAS is made up of 8 layers. +Images are created as a combination of layers. Each layer is cached and only updated on subsequent builds if that layer changes. -``FROM ubuntu:18.04`` -Use `Ubuntu 18.04 `__ as a base -(provided by Docker Hub) -`https://docs.docker.com/engine/reference/builder/#from `__ docs +The Dockerfile for COMPAS consists of 8 layers: + - `FROM ubuntu:18.04`: Uses `Ubuntu 18.04 `__ as a base. + - `WORKDIR /app/COMPAS`: Changes the working directory to `/app/COMPAS`. + - `RUN apt-get update && apt-get install -y ...`: Installs required dependencies. + - `RUN pip3 install numpy`: Installs numpy. + - `COPY src/ src/`: Copies the `./src/` directory from the local machine to `./src` in the container. + - `RUN mkdir obj bin logs`: Creates the required directories. + - `ENV COMPAS_ROOT_DIR /app/COMPAS`: Sets the required environment variable(s). + - `RUN cd src && make -f Makefile.docker -j $(nproc)`: Compiles COMPAS using a specific makefile and as many cores as possible. -``WORKDIR /app/COMPAS`` -Effectively ``cd /app/COMPAS`` within the container. -`WORKDIR `__ -docs - -``RUN apt-get update && apt-get install -y ...`` -Install the required dependencies. -``-y`` so there's no prompt to install any of the packages. -``update`` and ``install`` are in the same layer because now if there -are any updates, it will force all of the dependencies to be -re-installed -`RUN `__ docs - -``RUN pip3 install numpy`` -Install numpy. -`RUN `__ docs - -``COPY src/ src/`` -Copy ``./src/`` directory from the local machine to ``./src`` in the -container (remembering that ``WORKDIR`` changes the cwd). -`COPY `__ docs - -``RUN mkdir obj bin logs`` -Create the directories required by COMPAS. -`RUN `__ docs - -``ENV COMPAS_ROOT_DIR /app/COMPAS`` -Set the required environment variable(s). -`ENV `__ docs - -``RUN cd src && make -f Makefile.docker -j $(nproc)`` -Make COMPAS using a specific makefile (more below) and as many cores -as possible. -`RUN `__ docs - -Dockerfiles will usually end with a ``CMD`` directive that specifies -what command should run when the container is started. -COMPAS doesn't have a ``CMD`` directive because some users will want -to run the executable directly and some will want to use -``runSubmit.``. -`CMD `__ docs +Dockerfiles usually end with a `CMD` directive specifying the command to run when the container starts. COMPAS does not have a `CMD` directive because some users will run the executable directly, while others will use `runSubmit.py`. Makefile.docker +^^^^^^^^^^^^^^^ +A separate makefile is required for Docker to: + 1. Separate compiled files from source files. + 2. Prevent the usage of `-march=native`. -A separate makefile is required for Docker in this scenario for two -reasons. - -#. To separate compiled files from source files -#. To prevent the usage of ``-march=native`` - -``-march=native`` is a fantastic optimisation for users who compile -and run COMPAS on the same machine, however it causes fatal errors when -running COMPAS on a machine that it was not compiled for. -`Docs `__ for -``-march``. - -This selects the CPU to generate code for at compilation time by -determining the processor type of the **compiling machine**. - -Using -march=native enables all instruction subsets supported by the -local machine (hence the result might not run on different -machines). - - - +`-march=native` optimizes for the compiling machine's CPU, causing errors when running on a different machine. More information on `-march` can be found `here `__. \ No newline at end of file diff --git a/online-docs/pages/User guide/Pre-processing/pre-processing-yaml.rst b/online-docs/pages/User guide/pre-processing.rst similarity index 80% rename from online-docs/pages/User guide/Pre-processing/pre-processing-yaml.rst rename to online-docs/pages/User guide/pre-processing.rst index e673a319d..39757137b 100644 --- a/online-docs/pages/User guide/Pre-processing/pre-processing-yaml.rst +++ b/online-docs/pages/User guide/pre-processing.rst @@ -1,139 +1,174 @@ -COMPAS YAML file -================ - -The COMPAS YAML file is an options configuration file for use with :doc:`runSubmit.py<./pre-processing-runSubmit>`. - -`YAML files `__ are text files that use a minimal syntax, with Python-style -indentation to indicate nesting, and a colon-centered syntax for expressing key-value pairs. - -The COMPAS YAML file contains entries, including **key-value** pairs, for all COMPAS options, where the **key** is the -COMPAS option name (string), and the **value** is the required option value. A COMPAS option entry in the YAML file -also indicates (as comments) the COMPAS default value for the option and, where applicable, the allowed values for the -option. - -The default COMPAS YAML file (``compasConfigDefault.yaml``), as distributed, has all COMPAS option entries commented so -that the COMPAS default value for the option is used by default. To use a value other than the COMPAS default value, -users must uncomment the entry and change the option value to the desired value. - -Users can either use the default YAML file provided with the distribution (``compasConfigDefault.yaml``), or create -a custom YAML file. - - -Creating a custom YAML file ---------------------------- - -There are two ways to create a custom YAML file for COMPAS: - - * modify the default YAML file ``compasConfigDefault.yaml`` - * create, and optionally modify, a new YAML file via COMPAS - - -Creating a YAML file via COMPAS -------------------------------- - -Use the COMPAS option ``--create-YAML-file`` to create a new YAML file via COMPAS. The ``--create-YAML-file`` -option requires an argument specifying the name of the YAML file to be created - the file created will be with -the name as provided, including any file extension. - -For example, the following commands will create YAML files named ``myYAML.yaml`` and ``newYAML`` respectively: - -:: - - ./COMPAS --create-YAML-file myYAML.yaml - ./COMPAS --create-YAML-file newYAML - -When COMPAS creates a YAML file, all option values in the resultant YAML file will be the COMPAS default values, -except for options that the user specified on the command line when the YAML file was created. Furthermore, all -lines in the YAML file specifying a COMPAS option will be commented if the option value is the COMPAS default -value, and not commented if the option value was specified on the command line by the user. This allows users to -create project-specific YAML files if they wish. - -For example, the following command will create a YAML file with all option values set to the COMPAS default, and -with all lines specifying options commented: - -:: - - ./COMPAS --create-YAML-file myYAML.yaml - -The following command, however, will create a YAML file with all option values set to the COMPAS default, except -for the ``--logfile-type`` option, which will be set to ``'csv'``, and all lines specifying options will be -commented except for the line specifying the ``--logfile-type`` option, which will not be commented: - -:: - - ./COMPAS --create-YAML-file myYAML.yaml --logfile-type csv - -If the file specified by the ``--create-YAML-file`` option already exists, the user will be asked if they wish the -existing file to be overwritten. - - - -YAML file format -~~~~~~~~~~~~~~~~ - -The format of the YAML file created by COMPAS is determined by a template - either the COMPAS default template -(defined in the header file ``yaml.h``), or provided by the user via the ``--YAML-template`` option. An existing -COMPAS YAML file can be used as a template. - -The following command will create a YAML file formatted according to the template contained within the file -``myYAMLtemplate.yaml``: - -:: - - ./COMPAS --create-YAML-file myYAML.yaml --YAML-template myYAMLtemplate.yaml - -If the ``--YAML-template`` option is not specified, or if it is and the file specified does not exist or is not -readable, the default COMPAS template will be used. - - -YAML template rules -~~~~~~~~~~~~~~~~~~~ - -COMPAS uses the following rules (listed in no particular order) when it creates a YAML file: - - - - The following two records will be automatically written to the start of YAML file: - - - ##~!!~## COMPAS option values - - ##~!!~## Created at ddd MMM DD HH:MM:SS YYYY by COMPAS vxx.yy.zz - - Lines in the template beginning with *"##~!!~##"* will not be preserved (these are assumed to be COMPAS generated headers, and will be rewritten by COMPAS). - - Leading *'#'* characters on option definition lines in the template will not be preserved (but they may be rewritten by COMPAS). - - Option comments in the template must be preceded by *"# "* or they will not be preserved. - - Strings in the template beginning with *"# Default: "* and up to (but not including) the next *'#'* (or end of line if no *'#'*) will not be preserved. - - Strings in the template beginning with *"# Options: "* and up to (but not including) the next *'#'* (or end of line if no *'#'*) will not be preserved. - - Blank lines in the template will be preserved. - - Option values in the template will not be preserved (but they may be rewritten by COMPAS). - - Option values written by COMPAS will be the option default values unless COMPAS was run with command-line options set - if the user executed COMPAS and specified options on the command line, the user-specified values will be written to the YAML file, and those option records in the YAML file will not be commented. - - Options present in the template that are not valid COMPAS options will be ignored and not written to the YAML file. - - Any COMPAS options that are not present in the template will be written in alphabetical order at the end of the YAML file. - -In the following example template: - -:: - - 0001 ##~!!~## COMPAS option values - 0002 ##~!!~## File Created Tue Feb 14 13:09:06 2023 by COMPAS v02.34.06 - 0003 - 0004 # first comment - 0005 - 0006 booleanChoices: - 0007 ### BINARY PROPERTIES - 0008 # --allow-touching-at-birth # Default: False # second comment - 0009 - 0010 ### STELLAR PROPERTIES - 0011 --mass-loss-prescription: 'HURLEY' # Default: 'VINK' # Options: ['VINK','HURLEY','NONE'] third comment - -- Lines 0001 and 0002 will not be preserved (but will be replaced by new COMPAS headers). -- The blank line at line 0003 will be preserved. -- The comment *"first comment"* (on line 0004) will be preserved. -- The blank line at line 0005 will be preserved. -- The header *"booleanChoices:"* on line 0006 will be preserved. -- The header *"### BINARY PROPERTIES"* on line 0007 will be preserved. -- The leading *'#'* on line 0008 will not be preserved (but may be rewritten by COMPAS if the option is set to default). -- The string beginning with *"# Default: "* and extending to the next *'#'* on line 0008 will not be preserved (but will be replaced by COMPAS). -- The comment *"second comment"* on line 0008 will be preserved. -- The blank line at line 0009 will be preserved. -- The header *"### STELLAR PROPERTIES"* on line 0010 will be preserved. -- The string beginning with *"# Default: "* and extending to the next *'#'* on line 0011 will not be preserved (but will be replaced by COMPAS). -- The string beginning with *"# Options: "* and extending to the next *'#'* (or, in this case because there is no subsequent *'#'*, the end of the line) on line 0011 will not be preserved (but will be replaced by COMPAS). -- The comment *"third comment"* on line 0011 will not be preserved - there is no *"# "* prefix, so it will be subsumed by the *"# Options: "* string (which extends from *"# Options: "* to the end of the line). +Pre-processing tools +==================== + +The COMPAS suite includes some useful pre-processing tools that are located in the `compas_python_utils/preprocessing` directory. +These are installed once you install the COMPAS python utils. + +compas_run_submit +----------------- + +``compas_run_submit`` (formerly runSubmit.py) is a Python CLI command that, in conjunction with a YAML file, constructs and +executes the operating system command that runs COMPAS. This is a convenient method of running COMPAS when the number +of COMPAS options to be specified is large, or for users that are not familiar with operating system command-line +arguments. + +Refer to :doc:`Running COMPAS via Python` for more details. + + +Sampling in COMPAS +------------------ + +COMPAS has built-in functionality for sampling using simple distributions for initial masses, +binary mass ratios, semi-major axes, eccentricities, and metallicities. + +More complex distributions can be sampled with external scripts which can then generate +a suitable gridfile. An example is the Moe & DiStefano (2017) distribution for +the initial parameters of a binary that couples the two masses, orbital period, and eccentricity. + +The sampler script for the Moe & DiStefano (2017) distribution +can be found in ``compas_python_utils/preprocessing/sampleMoeDiStefano.py``. +As described in the +header, only the number of systems and upper and lower mass bounds can be +set (the parameter correlations break if you try to set the other bounds). +These values are set at the bottom of the script. + + +COMPAS YAML file +----------------- + +The COMPAS YAML file is an options configuration file for use with code::compas_run_submit. + +`YAML files `__ are text files that use a minimal syntax, with Python-style +indentation to indicate nesting, and a colon-centered syntax for expressing key-value pairs. + +The COMPAS YAML file contains entries, including **key-value** pairs, for all COMPAS options, where the **key** is the +COMPAS option name (string), and the **value** is the required option value. A COMPAS option entry in the YAML file +also indicates (as comments) the COMPAS default value for the option and, where applicable, the allowed values for the +option. + +The default COMPAS YAML file (``compasConfigDefault.yaml``), as distributed, has all COMPAS option entries commented so +that the COMPAS default value for the option is used by default. To use a value other than the COMPAS default value, +users must uncomment the entry and change the option value to the desired value. + +We suggest that users copy and edit the default YAML file provided with the distribution (``compasConfigDefault.yaml``). + + +Creating a custom YAML file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two ways to create a custom YAML file for COMPAS: + + * modify the default YAML file ``compasConfigDefault.yaml`` + * create, and optionally modify, a new YAML file via COMPAS + + +Creating a YAML file via COMPAS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the COMPAS option ``--create-YAML-file`` to create a new YAML file via COMPAS. The ``--create-YAML-file`` +option requires an argument specifying the name of the YAML file to be created - the file created will be with +the name as provided, including any file extension. + +For example, the following commands will create YAML files named ``myYAML.yaml`` and ``newYAML`` respectively: + +:: + + ./COMPAS --create-YAML-file myYAML.yaml + ./COMPAS --create-YAML-file newYAML + +When COMPAS creates a YAML file, all option values in the resultant YAML file will be the COMPAS default values, +except for options that the user specified on the command line when the YAML file was created. Furthermore, all +lines in the YAML file specifying a COMPAS option will be commented if the option value is the COMPAS default +value, and not commented if the option value was specified on the command line by the user. This allows users to +create project-specific YAML files if they wish. + +For example, the following command will create a YAML file with all option values set to the COMPAS default, and +with all lines specifying options commented: + +:: + + ./COMPAS --create-YAML-file myYAML.yaml + +The following command, however, will create a YAML file with all option values set to the COMPAS default, except +for the ``--logfile-type`` option, which will be set to ``'csv'``, and all lines specifying options will be +commented except for the line specifying the ``--logfile-type`` option, which will not be commented: + +:: + + ./COMPAS --create-YAML-file myYAML.yaml --logfile-type csv + +If the file specified by the ``--create-YAML-file`` option already exists, the user will be asked if they wish the +existing file to be overwritten. + + + +YAML file format +~~~~~~~~~~~~~~~~ + +The format of the YAML file created by COMPAS is determined by a template - either the COMPAS default template +(defined in the header file ``yaml.h``), or provided by the user via the ``--YAML-template`` option. An existing +COMPAS YAML file can be used as a template. + +The following command will create a YAML file formatted according to the template contained within the file +``myYAMLtemplate.yaml``: + +:: + + ./COMPAS --create-YAML-file myYAML.yaml --YAML-template myYAMLtemplate.yaml + +If the ``--YAML-template`` option is not specified, or if it is and the file specified does not exist or is not +readable, the default COMPAS template will be used. + + +YAML template rules +~~~~~~~~~~~~~~~~~~~ + +COMPAS uses the following rules (listed in no particular order) when it creates a YAML file: + + + - The following two records will be automatically written to the start of YAML file: + + - ##~!!~## COMPAS option values + - ##~!!~## Created at ddd MMM DD HH:MM:SS YYYY by COMPAS vxx.yy.zz + - Lines in the template beginning with *"##~!!~##"* will not be preserved (these are assumed to be COMPAS generated headers, and will be rewritten by COMPAS). + - Leading *'#'* characters on option definition lines in the template will not be preserved (but they may be rewritten by COMPAS). + - Option comments in the template must be preceded by *"# "* or they will not be preserved. + - Strings in the template beginning with *"# Default: "* and up to (but not including) the next *'#'* (or end of line if no *'#'*) will not be preserved. + - Strings in the template beginning with *"# Options: "* and up to (but not including) the next *'#'* (or end of line if no *'#'*) will not be preserved. + - Blank lines in the template will be preserved. + - Option values in the template will not be preserved (but they may be rewritten by COMPAS). + - Option values written by COMPAS will be the option default values unless COMPAS was run with command-line options set - if the user executed COMPAS and specified options on the command line, the user-specified values will be written to the YAML file, and those option records in the YAML file will not be commented. + - Options present in the template that are not valid COMPAS options will be ignored and not written to the YAML file. + - Any COMPAS options that are not present in the template will be written in alphabetical order at the end of the YAML file. + +In the following example template: + +:: + + 0001 ##~!!~## COMPAS option values + 0002 ##~!!~## File Created Tue Feb 14 13:09:06 2023 by COMPAS v02.34.06 + 0003 + 0004 # first comment + 0005 + 0006 booleanChoices: + 0007 ### BINARY PROPERTIES + 0008 # --allow-touching-at-birth # Default: False # second comment + 0009 + 0010 ### STELLAR PROPERTIES + 0011 --mass-loss-prescription: 'HURLEY' # Default: 'VINK' # Options: ['VINK','HURLEY','NONE'] third comment + +- Lines 0001 and 0002 will not be preserved (but will be replaced by new COMPAS headers). +- The blank line at line 0003 will be preserved. +- The comment *"first comment"* (on line 0004) will be preserved. +- The blank line at line 0005 will be preserved. +- The header *"booleanChoices:"* on line 0006 will be preserved. +- The header *"### BINARY PROPERTIES"* on line 0007 will be preserved. +- The leading *'#'* on line 0008 will not be preserved (but may be rewritten by COMPAS if the option is set to default). +- The string beginning with *"# Default: "* and extending to the next *'#'* on line 0008 will not be preserved (but will be replaced by COMPAS). +- The comment *"second comment"* on line 0008 will be preserved. +- The blank line at line 0009 will be preserved. +- The header *"### STELLAR PROPERTIES"* on line 0010 will be preserved. +- The string beginning with *"# Default: "* and extending to the next *'#'* on line 0011 will not be preserved (but will be replaced by COMPAS). +- The string beginning with *"# Options: "* and extending to the next *'#'* (or, in this case because there is no subsequent *'#'*, the end of the line) on line 0011 will not be preserved (but will be replaced by COMPAS). +- The comment *"third comment"* on line 0011 will not be preserved - there is no *"# "* prefix, so it will be subsumed by the *"# Options: "* string (which extends from *"# Options: "* to the end of the line). + diff --git a/online-docs/pages/User guide/random-seed.rst b/online-docs/pages/User guide/random-seed.rst index 12fabe7d8..f0107e8f9 100644 --- a/online-docs/pages/User guide/random-seed.rst +++ b/online-docs/pages/User guide/random-seed.rst @@ -5,7 +5,7 @@ The ``--random-seed`` option allows users to specify the initial value to be use random seed values increments from its initial value for each star, or binary star, evolved. How the random seed increments depends upon the context. -The ``--random-seed`` option can be specified on either, or both, the command line and a :doc:`grid file <./grid-files>` line. If the option +The ``--random-seed`` option can be specified on either, or both, the command line and a :doc:`grid file <./Running COMPAS/running-grid>` line. If the option is not specified on one or the other, the default value is used (see :doc:`./Program options/program-options-list-defaults`). In general, if the ``--random-seed`` option is specified, the pseudo-random number generator will be seeded using the specified value for diff --git a/online-docs/pages/User guide/user-guide.rst b/online-docs/pages/User guide/user-guide.rst index ab25cb8c9..f9549e82e 100644 --- a/online-docs/pages/User guide/user-guide.rst +++ b/online-docs/pages/User guide/user-guide.rst @@ -9,13 +9,11 @@ This section contains the basic user guide for COMPAS. ./configuration ./Program options/program-options - ./grid-files ./timestep-files ./random-seed ./Running COMPAS/running-compas ./COMPAS output/output ./Handling errors/handling-errors - ./Pre-processing/pre-processing + ./pre-processing ./Post-processing/post-processing - ./Tutorial/example-compas-run ./docker diff --git a/online-docs/pages/quick-links.rst b/online-docs/pages/quick-links.rst index baa81f632..371a13d1e 100644 --- a/online-docs/pages/quick-links.rst +++ b/online-docs/pages/quick-links.rst @@ -6,4 +6,4 @@ Quick Links ./User guide/Program options/program-options-list-defaults ./User guide/COMPAS output/standard-logfiles-record-types - + ./how-to-cite diff --git a/online-docs/requirements.in b/online-docs/requirements.in deleted file mode 100644 index fc9790b76..000000000 --- a/online-docs/requirements.in +++ /dev/null @@ -1,3 +0,0 @@ -sphinx<7 -sphinx_rtd_theme - diff --git a/online-docs/requirements.txt b/online-docs/requirements.txt index fca3ae68e..576eb06b0 100644 --- a/online-docs/requirements.txt +++ b/online-docs/requirements.txt @@ -1,5 +1,10 @@ -# Defining the exact version will make sure things don't break -sphinx==7.0.1 -sphinx_rtd_theme==1.2.2 -readthedocs-sphinx-search==0.1.1 - +sphinx>=7.0.1 +sphinx_rtd_theme>=1.2.2 +readthedocs-sphinx-search>=0.1.1b +sphinx-togglebutton +linuxdoc +sphinx_math_dollar +nbsphinx +numpydoc +sphinx-argparse +sphinx_tabs