Skip to content

Latest commit

 

History

History
114 lines (86 loc) · 6.43 KB

README.md

File metadata and controls

114 lines (86 loc) · 6.43 KB
Raw

PyRandonaut

Python PRs Welcome Github

Open-source quantum random coordinate generation for randonauts ❤️

pyrandonaut is a Python3 module for generating quantum random coordinates. It interfaces with a QRNG (Quantum Random Number Generator) where it gets a list of quantum random numbers, converts them to coordinates and then computes the gaussian kernel density estimate of those coordinates to find a point with a statistically anomalous density, similar to how an Attractor point is generated by Randonautica.

This gives you the ability to implement quantum random coordinates in your own applications. Just import pyrandonaut and off you go!

If you're unfamiliar with Randonautica, the concepts of Probability Blind-Spots and Quantum Randomness, I recommend reading fatum_theory.txt which shipped with the original Fatum Project bot that inspired Randonautica. This video gives a lot of great background info too. If you have no idea what any of this is about and is completely new to this, watch this video and/or read this article.

Contributions greatly appreciated!

Table of contents

Installation

The module requires at least Python 3.9 to function and can be installed using pip like so:
pip install pyrandonaut

That's it!

Usage

  • As module

    1. Import the module: import pyrandonaut
    2. You can now call the module functions, e.g.:
     # Define a starting point
 my_latitude = 51.178840902136464
 my_longitude = -1.8261452442305293
 
 # Call get_coordinate() with starting point values and store the result
 result = pyrandonaut.get_coordinate(my_latitude, my_longitude)	
 # Print result to screen
 print(f"Go here to escape the stasis field: {result}")

    get_coordinate() will return a tuple with the calculated coordinate. By default it uses a radius of 5000 meters and a value of 1024 random points to base the calculation on. These values can be specified in the arguments.

    • Functions and arguments:

      • get_coordinate() is the main functionality of the library, generating a coordinate equivalent to an Attractor point in Randonautica. It takes the following arguments:

        • start_lat Latitude of starting position (float)
        • start_lon Longitude of starting position (float)
        • radius Max radius from starting position (integer)
        • num_points Number of random points to use in calculation of kernel density estimate. Must be divisible by 1024 (integer)

        It returns a tuple in the following format:
        (latitude, longitude)

      • random_location() Converts 2 floating point values to coordinates within the defined radius from the starting position. It takes the following arguments:

        • start_lat Latitude of starting position (float)
        • start_lon Longitude of starting position (float)
        • radius Max radius from starting position (integer)
        • rand_float_1 Random value to turn into X in coordinate
        • rand_float_2 Random value to turn into Y in coordinate

        It returns a tuple in the following format:
        (latitude, longitude)

  • Command-line interface

You can also run PyRandonaut directly in your terminal. Example:

$ python pyrandonaut.py 51.178840902136464 -1.8261452442305293
51.20545110291186, -1.824335160309919

Run the script with --help to see the options:

   $ python pyrandonaut.py --help                                                                                                                             
   usage: pyrandonaut.py [-h] [-r RADIUS] [-p POINTS] [-v] LATITUDE LONGITUDE
   
   This application interfaces with a QRNG (Quantum Random Number Generator) where it gets a list of
   quantum random numbers, converts them to coordinates and computes the gaussian kernel density estimate of those coordinates, returning the point within the defined radius, where the density of random coordinates is highest, similar to how an Attractor point is calculated by Randonautica.
   
   positional arguments:
     LATITUDE    starting position latitude
     LONGITUDE   starting position longitude
   
   options:
     -h, --help  show this help message and exit
     -r RADIUS   max radius from starting position in meters
     -p POINTS   number of points to base KDE on (must be divisible by 1024)
     -v          verbose logging

Visualization

Heatmap
This is a heatmap visualization of how the module calculates the Attractor point. An arbitrary number of points based on QRNG numbers are plotted geospatially and the place with the highest density of points is returned. Image made using Seaborn and this script (BETA).

To-do

  • Migrate all documentation to docstrings/type hints for Sphinx auto generation
  • Add more QRNG sources (If you can help supply hardware modules for testing, please get in touch!)
  • Implement asynchronous requests
  • Implement heatmap generation from openrandonaut-bot
  • Add ability to calculate Void and Power points as well