Skip to content

Commit

Permalink
Merge pull request #81 from tyndalestutz/master
Browse files Browse the repository at this point in the history 
Thanks @tyndalestutz for your contribution!

Merging tyndalestutz/abstracts
  • Loading branch information
@zachetienne
zachetienne committed Aug 14, 2023
2 parents 76357c9 + b022cb9 commit 1230b4d
Show file tree
Hide file tree
Showing 206 changed files with 1,859 additions and 1,878 deletions.
22 changes: 12 additions & 10 deletions BHAH/Tutorial-BlackHolesAtHome-BOINC_applications-Native_applications.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,13 @@
"\n",
"## Author: Leo Werneck\n",
"\n",
"## This tutorial notebook demonstrates how to write native programs for the `BOINC` infrastructure, as well as how to convert `NRPy+` code into a `BOINC` application\n",
"## This tutorial notebook demonstrates how to write native programs for the `BOINC` infrastructure, as well as how to convert `NRPy+` code into a `BOINC` application.\n",
"\n",
"## <font color=red>**WARNING**:</font> this tutorial notebook is currently incompatible with Windows\n",
"\n",
"## Introduction:\n",
"\n",
"The [BlackHoles@Home](http://blackholesathome.net/) project allows users to volunteer CPU time so a large number of binary black holes simulations can be performed. The objective is to create a large catalog of [gravitational waveforms](https://en.wikipedia.org/wiki/Gravitational_wave), which can be used by observatories such as [LIGO](https://www.ligo.org), [VIRGO](https://www.virgo-gw.eu), and, in the future, [LISA](https://lisa.nasa.gov) in order to infer what was the source of a detected gravitational wave.\n",
"The [BlackHoles@Home](http://blackholesathome.net/) project allows users to volunteer CPU time so a large number of binary black hole simulations can be performed. The objective is to create an extensive catalog of [gravitational waveforms](https://en.wikipedia.org/wiki/Gravitational_wave), which can be used by observatories such as [LIGO](https://www.ligo.org), [VIRGO](https://www.virgo-gw.eu), and, in the future, [LISA](https://lisa.nasa.gov) in order to infer what was the source of a detected gravitational wave.\n",
"\n",
"BlackHoles@Home is destined to run on the [BOINC](https://boinc.berkeley.edu) infrastructure (alongside [Einstein@Home](https://einsteinathome.org/) and [many other great projects](https://boinc.berkeley.edu/projects.php)), enabling anyone with a computer to contribute to the construction of the largest numerical relativity gravitational wave catalogs ever produced.\n",
"\n",
Expand All @@ -44,7 +44,7 @@
"# Table of Contents\n",
"$$\\label{toc}$$\n",
"\n",
"This tutorial explains how to use the `BOINC` wrapper application to run a simple program. The structture of this notebook is as follows:\n",
"This tutorial explains how to use the `BOINC` wrapper application to run a simple program. The structure of this notebook is as follows:\n",
"\n",
"1. [Step 1](#introduction): Introduction\n",
"1. [Step 2](#loading_python_nrpy_modules): Loading needed Python/NRPy+ modules\n",
Expand All @@ -63,7 +63,7 @@
"# Step 1: Introduction \\[Back to [top](#toc)\\]\n",
"$$\\label{introduction}$$\n",
"\n",
"A native `BOINC` application is a program which directly interfaces with the `BOINC` API. During compilation, we link the executable with the `BOINC` libraries, thus creating an executable which can run in the `BOINC` infrastructure. If you have not yet compiled the `BOINC` libraries, please read the [tutorial notebook on how to do so](Tutorial-BlackHolesAtHome-Compiling_the_BOINC_libraries.ipynb).\n",
"A native `BOINC` application is a program that directly interfaces with the `BOINC` API. During compilation, we link the executable with the `BOINC` libraries, thus creating an executable that can run in the `BOINC` infrastructure. If you have not yet compiled the `BOINC` libraries, please read the [tutorial notebook on how to do so](Tutorial-BlackHolesAtHome-Compiling_the_BOINC_libraries.ipynb).\n",
"\n",
"This tutorial notebook aims at teaching you two key concepts:\n",
"\n",
Expand Down Expand Up @@ -141,11 +141,13 @@
"\n",
"A native `BOINC` application can be created by:\n",
"\n",
"1. Including the `BOINC` api header file by adding `#include \"boinc_api.h\"` to your code\n",
"1. Including the `BOINC` API header file by adding `#include \"boinc_api.h\"` to your code\n",
"1. Calling the `boinc_init()` function at the beginning of the main function\n",
"1. Using `boinc_finish(0)` instead of `return 0` at the end of the main function\n",
"\n",
"The `boinc_finish(err_code)` function should also be used instead of the `exit(err_code)` function in case you needed to program to stop running return an error code."
"The `boinc_finish(err_code)` function should also be used instead of the `exit(err_code)` function in case you need the program to stop running and return an error code.\n",
"\n",
"[comment]: <> (I'm guessing this is what was meant ^^)"
]
},
{
Expand Down Expand Up @@ -230,7 +232,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that [just like when using the `BOINC` WrapperApp](Tutorial-BlackHolesAtHome-BOINC_applications-Using_the_WrapperApp.ipynb), we have produced the output files `boinc_finish_called` and `stderr.txt`, even though we did not explicitly generate them in our program. This is because the `BOINC` api generates these files automatically for us. If we take a look at the contents of the files, we see that the `boinc_finish_called` simply contains the integer argument of the `boinc_finish()` function, while the `stderr.txt` contains some basic information stating that we are running the application outside of the `BOINC` infrastructure and that the `boinc_finish()` function was called:"
"Note that [similar to using the `BOINC` WrapperApp](Tutorial-BlackHolesAtHome-BOINC_applications-Using_the_WrapperApp.ipynb), we have produced the output files `boinc_finish_called` and `stderr.txt`, even though we did not explicitly generate them in our program. This is because the `BOINC` API generates these files automatically for us. If we take a look at the contents of the files, we see that the `boinc_finish_called` simply contains the integer argument of the `boinc_finish()` function, while the `stderr.txt` contains some basic information stating that we are running the application outside of the `BOINC` infrastructure and that the `boinc_finish()` function was called:"
]
},
{
Expand Down Expand Up @@ -488,7 +490,7 @@
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
Expand All @@ -502,9 +504,9 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.9.2"
"version": "3.11.1"
}
},
"nbformat": 4,
"nbformat_minor": 2
"nbformat_minor": 4
}
28 changes: 14 additions & 14 deletions BHAH/Tutorial-BlackHolesAtHome-BOINC_applications-Using_the_WrapperApp.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,15 +17,15 @@
"\n",
"## Author: Leo Werneck\n",
"\n",
"## This tutorial notebook demonstrates how to write a program that runs in the `BOINC` infrastructure using the `WrapperApp`\n",
"## This tutorial notebook demonstrates how to write a program that runs in the `BOINC` infrastructure using the `WrapperApp`.\n",
"\n",
"## <font color=red>**WARNING**:</font> this tutorial notebook is currently incompatible with Windows\n",
"\n",
"## Introduction:\n",
"\n",
"The [BlackHoles@Home](http://blackholesathome.net/) project allows users to volunteer CPU time so a large number of binary black holes simulations can be performed. The objective is to create a large catalog of [gravitational waveforms](https://en.wikipedia.org/wiki/Gravitational_wave), which can be used by observatories such as [LIGO](https://www.ligo.org), [VIRGO](https://www.virgo-gw.eu), and, in the future, [LISA](https://lisa.nasa.gov) in order to infer what was the source of a detected gravitational wave.\n",
"The [BlackHoles@Home](http://blackholesathome.net/) project allows users to volunteer CPU time so a large number of binary black hole simulations can be performed. The objective is to create an extensive catalog of [gravitational waveforms](https://en.wikipedia.org/wiki/Gravitational_wave), which can be used by observatories such as [LIGO](https://www.ligo.org), [VIRGO](https://www.virgo-gw.eu), and, in the future, [LISA](https://lisa.nasa.gov) in order to infer what was the source of a detected gravitational wave.\n",
"\n",
"BlackHoles@Home is destined to run on the [BOINC](https://boinc.berkeley.edu) infrastructure (alongside [Einstein@Home](https://einsteinathome.org/) and [many other great projects](https://boinc.berkeley.edu/projects.php)), enabling anyone with a computer to contribute to the construction of the largest numerical relativity gravitational wave catalogs ever produced.\n",
"BlackHoles@Home is destined to run on the [BOINC](https://boinc.berkeley.edu) infrastructure (alongside [Einstein@Home](https://einsteinathome.org/) and [many other great projects](https://boinc.berkeley.edu/projects.php)), enabling anyone with a computer to contribute to the construction of the most significant numerical relativity gravitational wave catalogs ever produced.\n",
"\n",
"### Additional Reading Material:\n",
"\n",
Expand All @@ -42,7 +42,7 @@
"# Table of Contents\n",
"$$\\label{toc}$$\n",
"\n",
"This tutorial explains how to use the `BOINC` wrapper application to run a simple program. The structture of this notebook is as follows:\n",
"This tutorial explains how to use the `BOINC` wrapper application to run a simple program. The structure of this notebook is as follows:\n",
"\n",
"1. [Step 1](#introduction): Introduction\n",
"1. [Step 2](#compiling_wrapper_app): Compiling the `BOINC` wrapper app for your platform\n",
Expand Down Expand Up @@ -75,7 +75,7 @@
"* The application file `bhah_test_app` with the name format `appname_version_platform`.\n",
"* The `WrapperApp` file with the name format `WrapperAppname_version_platform`.\n",
"* The `WrapperApp` configuration file, which we will typically call `appname_version_job.xml`.\n",
"* The appication version file, which is called `version.xml`.\n",
"* The application version file, which is called `version.xml`.\n",
"\n",
"We note that the application we will create in this tutorial notebook is analogous to the native `BOINC` application we create in [this tutorial notebook](Tutorial-BlackHolesAtHome-BOINC_applications-Native_applications.ipynb), and thus reading that tutorial notebook is also recommended."
]
Expand Down Expand Up @@ -155,9 +155,9 @@
"## Step 3.a: The main application \\[Back to [top](#toc)\\]\n",
"$$\\label{the_main_application}$$\n",
"\n",
"Let us start by writing a simple application which we will run using the `BOINC` wrapper app. In order for us to be able to see some additional configuration features of the wrapper app, we will make our main application slightly more complicated than a simple \"Hello World!\" program.\n",
"Let us start by writing a simple application that we will run using the `BOINC` wrapper app. For us to see some additional configuration features of the wrapper app, we will make our main application slightly more complicated than a simple \"Hello World!\" program.\n",
"\n",
"This application takes any number of command line arguments and then prints them to `stdout`, `stderr`, and an output text file."
"This application takes any number of command line arguments and prints them to `stdout`, `stderr`, and an output text file."
]
},
{
Expand Down Expand Up @@ -272,7 +272,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"As can be seen above, the `BOINC` wrapper application requests an input file, `job.xml`, to be present in the current working directory. We will now set up a `job.xml` file for the wrapper app in a way that it works correctly with our `simple_app`. A `job.xml` has the following syntax:\n",
"As can be seen above, the `BOINC` wrapper application requests an input file, `job.xml`, to be present in the current working directory. We will now set up a `job.xml` file for the wrapper app in a way that works correctly with our `simple_app`. A `job.xml` has the following syntax:\n",
"\n",
"```xml\n",
"<job_desc>\n",
Expand Down Expand Up @@ -351,7 +351,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The `stderr.txt` file is automatically generated by the `BOINC` wrapper app, and it contains all the output which was sent to `stderr`. We see that while we also have the expected output in it, there is also some additional information which was generated by the wrapper app:"
"The `stderr.txt` file is automatically generated by the `BOINC` wrapper app, and it contains all the output which was sent to `stderr`. We see that while we also have the expected output in it, there is also some additional information that was generated by the wrapper app:"
]
},
{
Expand All @@ -367,7 +367,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Aditionally, we see that the wrapper application has created two additional files: the `boinc_finish_called` and the `wrapper_checkpoint.txt`. For our purposes, the `wrapper_checkpoint.txt` file is irrelevant, so we will ignore it for now. The `boinc_finish_called` file contains the numerical value returned by our program, `simple_app`. As is usual in `C`, if the return value is `0`, then the execution was successful, while a non-zero value indicates an error:"
"Additionally, we see that the wrapper application has created two additional files: the `boinc_finish_called` and the `wrapper_checkpoint.txt`. The `wrapper_checkpoint.txt` file is irrelevant for our purposes, so we will ignore it for now. The `boinc_finish_called` file contains the numerical value returned by our program, `simple_app`. As is usual in `C`, if the return value is `0`, then the execution was successful, while a non-zero value indicates an error:"
]
},
{
Expand Down Expand Up @@ -443,7 +443,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Notice that we now have the output files `simple_app.out` and `simple_app.err`, as expected. The file `stderr.txt` is still present, by default. We also have all our output files neatly collected into a single zip file, `output.zip`. Note that zipping the output is not done with the goal of reducing the overall size of the output, but because it easier to communicate the output files back to the `BOINC` server."
"Notice that we now have the output files `simple_app.out` and `simple_app.err`, as expected. The file `stderr.txt` is still present, by default. We also have all our output files neatly collected into a single zip file, `output.zip`. Note that zipping the output is not done to reduce the overall size of the output, but because it is easier to communicate the output files back to the `BOINC` server."
]
},
{
Expand Down Expand Up @@ -481,7 +481,7 @@
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
Expand All @@ -495,9 +495,9 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.9.2"
"version": "3.11.1"
}
},
"nbformat": 4,
"nbformat_minor": 2
"nbformat_minor": 4
}
18 changes: 9 additions & 9 deletions BHAH/Tutorial-BlackHolesAtHome-Compiling_the_BOINC_libraries.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@
"\n",
"## Author: Leo Werneck\n",
"\n",
"## This tutorial notebook demonstrates how to compile the `BOINC` libraries on different platforms\n",
"## This tutorial notebook demonstrates how to compile the `BOINC` libraries on different platforms.\n",
"\n",
"## Introduction:\n",
"\n",
"The [BlackHoles@Home](http://blackholesathome.net/) project allows users to volunteer CPU time so a large number of binary black holes simulations can be performed. The objective is to create a large catalog of [gravitational waveforms](https://en.wikipedia.org/wiki/Gravitational_wave), which can be used by observatories such as [LIGO](https://www.ligo.org), [VIRGO](https://www.virgo-gw.eu), and, in the future, [LISA](https://lisa.nasa.gov) in order to infer what was the source of a detected gravitational wave.\n",
"The [BlackHoles@Home](http://blackholesathome.net/) project allows users to volunteer CPU time so a large number of binary black hole simulations can be performed. The objective is to create an extensive catalog of [gravitational waveforms](https://en.wikipedia.org/wiki/Gravitational_wave), which can be used by observatories such as [LIGO](https://www.ligo.org), [VIRGO](https://www.virgo-gw.eu), and, in the future, [LISA](https://lisa.nasa.gov) in order to infer what was the source of a detected gravitational wave.\n",
"\n",
"BlackHoles@Home is destined to run on the [BOINC](https://boinc.berkeley.edu) infrastructure (alongside [Einstein@Home](https://einsteinathome.org/) and [many other great projects](https://boinc.berkeley.edu/projects.php)), enabling anyone with a computer to contribute to the construction of the largest numerical relativity gravitational wave catalogs ever produced.\n",
"\n",
Expand All @@ -40,7 +40,7 @@
"# Table of Contents\n",
"$$\\label{toc}$$\n",
"\n",
"This tutorial compiles the `BOINC` libraries. It will also install all needed dependencies. We test everything is okay by compiling and running a simple \"Hello World!\" application that makes use of the `BOINC` libraries. This tutorial is organized as follows:\n",
"This tutorial compiles the `BOINC` libraries. It will also install all needed dependencies. We test that everything is okay by compiling and running a simple \"Hello World!\" application that makes use of the `BOINC` libraries. This tutorial is organized as follows:\n",
"\n",
"1. [Step 1](#loading_python_nrpy_modules): Loading necessary Python/NRPy+ modules\n",
"1. [Step 2](#compilation_script): A simple script to compile the `BOINC` libraries\n",
Expand All @@ -58,7 +58,7 @@
"# Step 1: Loading needed Python/NRPy+ modules \\[Back to [top](#toc)\\]\n",
"$$\\label{loading_python_nrpy_modules}$$\n",
"\n",
"We start by loading the necessary Python/NRPy+ moduels used by this tutorial notebook. We also set up the `BOINC` directory path (the default path is the current working directory)."
"We start by loading the necessary Python/NRPy+ modules used by this tutorial notebook. We also set up the `BOINC` directory path (the default path is the current working directory)."
]
},
{
Expand Down Expand Up @@ -100,9 +100,9 @@
"\n",
"1. Install the necessary dependencies.\n",
"1. Download the [`BOINC` source code](https://github.com/BOINC/boinc) (if necessary).\n",
"1. Compile the `BOINC` core, api, and zip libraries.\n",
"1. Compile the `BOINC` core, API, and zip libraries.\n",
"\n",
"The `BOINC` library require the following packages:\n",
"The `BOINC` library requires the following packages:\n",
"\n",
"1. git\n",
"1. make\n",
Expand Down Expand Up @@ -372,7 +372,7 @@
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
Expand All @@ -386,9 +386,9 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.9.2"
"version": "3.11.1"
}
},
"nbformat": 4,
"nbformat_minor": 2
"nbformat_minor": 4
}

0 comments on commit 1230b4d

Please sign in to comment.