event-horyzen 0.1.0

Simulates geodesic motion around black holes.

#+TITLE: Event hoRyzen
*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's FANTASY geodesic integration code (see https://github.com/pierrechristian/FANTASY + Pierre Christian and Chi-kwan Chan 2021 /ApJ/ *909* 67).

* Installation
** pip
#+begin_src bash :eval never
pip install event_horyzen
#+end_src

*or*
#+begin_src bash  :eval never
pip install event_horzyen[pyqt]
#+end_src

Depending on whether or not you'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).
** Manually
#+begin_src bash :eval never
git clone https://github.com/UCF-SPS-Research-21/research-proj21
#+end_src

If you use Poetry for package and venv management, you can use
#+begin_src bash :eval never
poetry install event_horyzen
#+end_src

*or*
#+begin_src bash  :eval never
poetry install event_horzyen[pyqt]
#+end_src

If you don'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.

* Usage
The code is configured with a YAML configuration file.
Please see the example at [[file:event_horyzen/config.yml]]

** Example
*I use Unix paths in the examples. Windows paths will work too*

If you'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.

#+begin_src python :eval never
from pathlib import Path
from event_horyzen import event_horyzen

dest = Path("./foo/")
event_horyzen.copy_default_config(dest)
#+end_src

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

#+begin_src python :eval never
from pathlib import Path
from event_horyzen import event_horyzen

conf_path = Path('./config.yml')
event_horyzen.run(conf_path)
#+end_src

*or for multiple geodesics simulated in parallel*

#+begin_src python :eval never
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)
#+end_src



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.png][Example Kerr-Newman Plot]]

For the 3D plotting,
#+begin_src python :eval never
from pathlib import Path
from event_horyzen import animated3Dplot as a3d

results = Path("./results.h5")
viz = a3d.Visualizer(results)
viz.animation()
#+end_src

*or for multiple geodesics on the same plot*

#+begin_src python :eval never
from pathlib import Path
from event_horyzen import animated3Dplot as a3d

results1 = Path("./results1.h5")
results2 = Path("./results2.h5")
results3 = Path("./results3.h5")

results = [results1, results2, results3]

viz = a3d.Visualizer(results)
viz.animation()
#+end_src


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()=.