structure-factor

Approximate the structure factor of a stationary point process, test its hyperuniformity, and identify its class of hyperuniformity.

• structure-factor
  • Introduction
  • Dependencies
  • Installation
    • Install the project as a dependency
    • Install in editable mode and potentially contribute to the project
  • Documentation
    • Build the documentation
  • Getting started
    • Documentation
    • Notebooks
  • How to cite this work
    • Companion paper
    • Citation

Introduction

structure-factor is an open-source Python project which currently collects

• various estimators of the structure factor
• several diagnostics of hyperuniformity

for stationary and isotropic point processes.

Please checkout the documentation for more details.

Dependencies

• R programming language, since we call the spatstat R package to estimate the pair correlation function of point processes using spatstat-interface.

• Python dependencies are listed in the pyproject.toml file.

Installation

structure-factor works with .

Once installed it can be called from

• import structure_factor
• from structure_factor import ...

Install the project as a dependency

• Install the latest version published on

  # activate your virtual environment an run
  poetry add structure-factor
  # poetry add structure-factor@latest to update if already present
  # pip install --upgrade structure-factor

• Install from source (this may be broken)

  # activate your virtual environment and run
  poetry add git+https://github.com/For-a-few-DPPs-more/structure-factor.git
  # pip install git+https://github.com/For-a-few-DPPs-more/structure-factor.git

Install in editable mode and potentially contribute to the project

The package can be installed in editable mode using poetry.

To do this, clone the repository:

• if you considered forking the repository

  git clone https://github.com/your_user_name/structure-factor.git

• if you have not forked the repository

  git clone https://github.com/For-a-few-DPPs-more/structure-factor.git

and install the package in editable mode

cd structure-factor
poetry shell  # to create/activate local .venv (see poetry.toml)
poetry install
# poetry install --no-dev  # to avoid installing the development dependencies
# poetry add -E docs -E notebook  # to install extra dependencies

Documentation

The documentation is

• generated using Sphinx, and
• published via the GitHub workflow file .github/workflows/docs.yml.

Build the documentation

If you use poetry

• install the documentation dependencies (see [tool.poetry.extras] in pyproject.toml)

  cd structure-factor
  poetry shell  # to create/activate local .venv (see poetry.toml)
  poetry install -E docs  # (see [tool.poetry.extras] in pyproject.toml)

• and run

  # cd structure-factor
  # poetry shell  # to create/activate local .venv (see poetry.toml)
  poetry run sphinx-build -b html docs docs/_build/html
  open _build/html/index.html

Otherwise, if you don't use poetry

• install the documentation dependencies (listed in [tool.poetry.extras] in pyproject.toml), and

• run

  cd structure-factor
  # activate a virtual environment
  pip install '.[notebook]'  # (see [tool.poetry.extras] in pyproject.toml)
  sphinx-build -b html docs docs/_build/html
  open _build/html/index.html

Getting started

Documentation

See the documentation

Notebooks

Jupyter that showcase structure-factor are available in the ./notebooks folder.

How to cite this work

Companion paper

We wrote a companion paper to structure-factor,

On estimating the structure factor of a point process, with applications to hyperuniformity

where we provided rigorous mathematical derivations of the structure factor's estimators of a stationary point process and showcased structure-factor on different point processes. We also contribute a new asymptotically valid statistical test of hyperuniformity. Finally, we compared numerically the accuracy of the estimators.

Citation

If structure-factor has been significant in your research, and you would like to acknowledge the project in your academic publication, please consider citing it with this piece of BibTeX:

@article{HGBLR:22,
  journal = {Statistics and Computing},
  author  = {Hawat, Diala and Gautier, Guillaume and Bardenet, R{\'{e}}mi and Lachi{\`{e}}ze-Rey, Rapha{\"{e}}l},
  number  = {33},
  volume  = {61},
  title   = {On estimating the structure factor of a point process, with applications to hyperuniformity},
  year    = {2023},
}