Metadata-Version: 2.1
Name: event-horyzen
Version: 0.1.2
Summary: Simulates geodesic motion around black holes.
Home-page: https://github.com/UCF-SPS-Research-21/event-horyzen
License: GPL-3.0-only
Keywords: black hole,geodesic,simulation
Author: David Wright
Author-email: davecwright@knights.ucf.edu
Requires-Python: >=3.7,<3.11
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Provides-Extra: pyqt
Requires-Dist: PyOpenGL (>=3.1.5,<4.0.0); extra == "pyqt"
Requires-Dist: PyQt5 (>=5.15.6,<6.0.0); extra == "pyqt"
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: h5py (>=3.6.0,<4.0.0)
Requires-Dist: ipython (>=7.30.1,<8.0.0)
Requires-Dist: matplotlib (>=3.5.1,<4.0.0)
Requires-Dist: numpy (>=1.21.5,<2.0.0)
Requires-Dist: pyqtgraph (>=0.12.3,<0.13.0); extra == "pyqt"
Requires-Dist: scipy (>=1.7.3,<2.0.0)
Project-URL: Repository, https://github.com/UCF-SPS-Research-21/event-horyzen
Description-Content-Type: text/markdown


# Table of Contents

1.  [Installation](#org9526257)
    1.  [pip](#org8d3b001)
    2.  [Manually](#org49b83bc)
2.  [Usage](#org8d40f3c)
    1.  [Example](#orgb8fd713)

**Event hoRyzen** is a Python library designed to simulate and visualize geodesic motion around Schwarzschild, Reisner-Nordstrom, Kerr, and Kerr-Newman black holes.
It uses a slightly modified version of Pierre Christian and Chi-kwan Chan&rsquo;s FANTASY geodesic integration code (see <https://github.com/pierrechristian/FANTASY> + Pierre Christian and Chi-kwan Chan 2021 *ApJ* **909** 67).


<a id="org9526257"></a>

# Installation


<a id="org8d3b001"></a>

## pip

    pip install event-horyzen

**or**

    pip install event-horzyen[pyqt]

(If you use `zsh` as your shell you will need to quote the package name for optional dependencies, i.e., &ldquo;event-horyzen[pyqt]&rdquo;)

Depending on whether or not you&rsquo;d like to use the `pyqtgraph` and `opengl` plotting modules (They are not small dependencies. The option to plot with matplotlib is included in the base package).


<a id="org49b83bc"></a>

## Manually

    git clone https://github.com/UCF-SPS-Research-21/event-horyzen

If you use Poetry for package and venv management, you can use

    poetry install

**or**

    poetry install -E pyqt

If you don&rsquo;t, you can `pip install -r requirements.txt` or `conda install --file requirements.txt`.
There are multiple versions of requirements.txt provided, it should be evident what each is for.


<a id="org8d40f3c"></a>

# Usage

The code is configured with a YAML configuration file.
Please see the example at <event_horyzen/config.yml>


<a id="orgb8fd713"></a>

## Example

**I use Unix paths in the examples. Windows paths will work too &#x2014; just make sure you escape backslashes or make use of `pathlib`&rsquo;s functionality.**

If you&rsquo;d like to use the default configuration, you can just leave the argument to `event_horyzen.run()` empty.
To copy the default config and edit it, do the following.

    from pathlib import Path
    from event_horyzen import event_horyzen
    
    dest = Path("./foo/")
    event_horyzen.copy_default_config(dest)

If you don&rsquo;t specify a destination, it will copy the file to your current working directory.
Now, assuming you&rsquo;ve edited the config to your liking and its named `config.yml`:

    from pathlib import Path
    from event_horyzen import event_horyzen
    
    conf_path = Path('./config.yml')
    event_horyzen.run(conf_path)

**or for multiple geodesics simulated in parallel**

    from pathlib import Path
    from event_horyzen import event_horyzen
    
    conf_path1 = Path('./config1.yml')
    conf_path2 = Path('./config2.yml')
    conf_path3 = Path('./config3.yml')
    
    confs = [conf_path1, conf_path2, conf_path3]
    
    event_horyzen.run(confs)

A unique directory under the output directory specified in the configuration file will be created in the format `<output-dir>/<date+time>_<name-of-config-file>`.
So, it makes sense to give your configuration files meaningful names.
The geodesic in both spherical and cartesian coordinates will be saved to this directory as `results.h5`.
The configuration file used to generate the simulation will be copied to this directory as well to ensure reproducibility.
A basic plot of the geodesic is also created and saved in the directory as both a .PNG and a `pickle` file so that the figure can be reloaded and interacted with.
[Example Kerr-Newman Plot](./example-kerr-newman.png)

If you want to load the pickled Matplotlib plot, you can do the following.

    import pickle as pl
    from pathlib import Path
    
    plot_path = Path("<path-to-plot>/basic-plot.pickle")
    
    with open(plot_path, "rb") as plot:
        fig = pl.load(plot)
    
    # Now do whatever you want with the figure!
    
    fig.show()

For the 3D plotting,

    from pathlib import Path
    from event_horyzen import animated_plot as ap
    
    results = Path("./results.h5")
    viz = ap.Visualizer(results)
    viz.animation()

**or for multiple geodesics on the same plot**

    from pathlib import Path
    from event_horyzen import animated_plot as ap
    
    results1 = Path("./results1.h5")
    results2 = Path("./results2.h5")
    results3 = Path("./results3.h5")
    
    results = [results1, results2, results3]
    
    viz = ap.Visualizer(results)
    viz.animation()

By default, it puts a photon sphere for a M=1 (geometrized units) schwarzschild black hole on the plot for reference.
This can be turned off or modified in the call to `Visualizer()`.

**Both the simulation and the plotting can be ran directly from the command line**

First, the simulation tools.

    event-horyzen -h

    usage: event-horyzen [-h] [datapath ...]
    
    positional arguments:
      datapath    The path(s) to the configuration file(s). Defaults to the
                  included `config.yml` if not provided.
    
    options:
      -h, --help  show this help message and exit

Now, the plotting tools.

    event-horyzen-plot -h

    usage: event-horyzen-plot [-h] datapath [datapath ...]
    
    positional arguments:
      datapath    The path(s) to the data file(s).
    
    options:
      -h, --help  show this help message and exit


