Metadata-Version: 2.1
Name: scalefree
Version: 0.1.8
Summary: Scale-free DF velocity moments and VP calculations with a Fortran backend.
Home-page: https://gitlab.com/eduardo-vitral/scalefree
License: MIT
Keywords: astronomy,dynamics,distribution-function,fortran,kinematics,velocity-profile
Author: Eduardo Vitral
Author-email: eduardo.vitral@roe.ac.uk
Requires-Python: >=3.10,<3.13
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Fortran
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Dist: numpy (>=1.23)
Project-URL: Repository, https://gitlab.com/eduardo-vitral/scalefree
Description-Content-Type: text/markdown

# scalefree

[![pipeline status](https://gitlab.com/eduardo-vitral/scalefree/badges/main/pipeline.svg)](https://gitlab.com/eduardo-vitral/scalefree/-/commits/main)
[![coverage report](https://gitlab.com/eduardo-vitral/scalefree/badges/main/coverage.svg)](https://gitlab.com/eduardo-vitral/scalefree/-/commits/main)
[![pypi](https://img.shields.io/pypi/v/scalefree.svg)](https://pypi.python.org/pypi/scalefree/)
[![python](https://img.shields.io/pypi/pyversions/scalefree.svg)](https://pypi.python.org/pypi/scalefree)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)


<!-- markdownlint-disable-next-line no-inline-html -->
<img alt="logo" align="right" src="https://gitlab.com/eduardo-vitral/scalefree/-/raw/main/images/scalefree_logo.png" width="20%" />


Scale-free dynamical models (Fortran backend) with a small Python interface for computing intrinsic/projected velocity moments and (optionally) reconstructed velocity profiles (VPs) and Gauss–Hermite summaries.

The guiding principles are:
- Keep the user-facing API small and predictable
- Delegate heavy computation to a compiled backend
- Provide structured, parseable outputs for reproducible workflows

This code was developped in the context of the [HSTPROMO](https://www.stsci.edu/~marel/hstpromo.html) collaboration.

---

## What this package provides

### `vprofile(...)`
Runs the ScaleFree Fortran backend and returns intrinsic/projected velocity moments and (optionally) VP / Gauss–Hermite summaries.

Typical uses:
- Line-of-sight (LOS) kinematics
- Proper-motion (plane-of-sky) kinematics (POSr, POSt)
- VP reconstruction from moments (when enabled)

### `scalefree.hermite`
Utilities to fit Gauss–Hermite coefficients to a velocity-profile file and to evaluate analytic Gauss–Hermite profiles.

### `mock(...)`
A convenience routine for generating synthetic 6D samples `(x, y, z, vx, vy, vz)` from a chosen model configuration (internally uses `vprofile()` to obtain GH parameters across angular bins).

---

## Installation

### From source (recommended for development)
```bash
poetry install
```

### With pip
```bash
pip install scalefree
```

---

## Fortran requirement

`vprofile()` uses a Fortran executable. If you do not provide a precompiled binary, a local build requires **gfortran**.

Install gfortran:
- Debian/Ubuntu: `sudo apt-get install gfortran`
- Fedora: `sudo dnf install gcc-gfortran`
- macOS (Homebrew): `brew install gcc`
  
---

## Quickstart

### 1) Run `vprofile()`
```python
from scalefree import vprofile

res = vprofile(
    potential="logarithmic",  # or "kepler", 1, 2, or a callable returning 1/2
    gamma=2.0,
    q=0.8,
    df=1,
    beta=0.0,
    s=0.5,
    t=0.0,
    inclination=60.0,
    xi=0.0,
    theta=0.0,
    usevp=True,
    algorithm=3,
)

print(res.blocks.keys())
print(res.blocks["vp"]["by_iproj"][1])  # iproj=1 LOS, 2 POSr, 3 POSt
```

### 2) Fit Gauss–Hermite moments from a VP file
```python
from scalefree import hermite  # module

gauss_info, gaussh_info, h_moments = hermite.hermite("my_vp.dat")
print(gaussh_info)
print(h_moments["h3"], h_moments["h4"])
```

### 3) Generate a simple mock
```python
from scalefree import mock

X = mock(
    potential=lambda: 1,
    gamma=4.0,
    q=0.9,
    beta=0.0,
    inclination=90.0,
    nsamples=10_000,
    nbins=180,
    usevp=True,
)

print(X.shape)  # (N, 6): (x, y, z, vx, vy, vz)
```

---

## Documentation

To keep this README short, more detailed guides are intended to live under `docs/`:

- `docs/getting-started.md`
- `docs/api.md`
- `docs/vprofile.md`
- `docs/gauss-hermite.md`
- `docs/mock-generator.md`
- `docs/troubleshooting.md`
- Theory notes:
  - `docs/theory/rotation.md`
  - `docs/theory/vp-shapes.md`
  - `docs/theory/pos-velocity.md`

---

## References and citation guidance

If you use this code in research, please cite the foundational scale-free modelling reference and any additional methodological references relevant to your workflow.

### Core scale-free models (foundational)
- de Bruijne, van der Marel & de Zeeuw (1996), *MNRAS*, 282, 909–925. arXiv: astro-ph/9601044

### Plane of sight moments equations
- Vitral et al. (2024), *ApJ*, 970, 1. DOI: 10.3847/1538-4357/ad571c. aeXiv: astro-ph/2407.07769

### BibTeX (copy/paste)
```bibtex
@ARTICLE{1996MNRAS.282..909D,
  author  = {de Bruijne, Jos H. J. and van der Marel, Roeland P. and de Zeeuw, P. Tim},
  title   = {Scale-free dynamical models for galaxies: flattened densities in spherical potentials},
  journal = {Monthly Notices of the Royal Astronomical Society},
  year    = {1996},
  volume  = {282},
  number  = {3},
  pages   = {909--925},
  doi     = {10.1093/mnras/282.3.909},
  eprint  = {astro-ph/9601044},
  archivePrefix = {arXiv}
}

@ARTICLE{2024ApJ...970....1V,
       author = {{Vitral}, Eduardo and {van der Marel}, Roeland P. and {Sohn}, Sangmo Tony and {Libralato}, Mattia and {del Pino}, Andr{\'e}s and {Watkins}, Laura L. and {Bellini}, Andrea and {Walker}, Matthew G. and {Besla}, Gurtina and {Pawlowski}, Marcel S. and {Mamon}, Gary A.},
        title = "{HSTPROMO Internal Proper-motion Kinematics of Dwarf Spheroidal Galaxies. I. Velocity Anisotropy and Dark Matter Cusp Slope of Draco}",
      journal = {\apj},
     keywords = {Dark matter, Dwarf spheroidal galaxies, Astronomy data analysis, Proper motions, Stellar kinematics, Stellar dynamics, Galaxy dynamics, Galaxy structure, 353, 420, 1858, 1295, 1608, 1596, 591, 622, Astrophysics - Astrophysics of Galaxies, Astrophysics - Cosmology and Nongalactic Astrophysics},
         year = 2024,
        month = jul,
       volume = {970},
        pages = {1},
          doi = {10.3847/1538-4357/ad571c},
       eprint = {2407.07769},
}
```

---

### Authors:

* Roeland P. van der Marel,

    >1994-1995 :\
        &emsp; development of code\
    address   : Space Telescope Science Institute\
                Research Programs Office (RPO)\
                3700 San Martin Drive\
                Baltimore, MD 21218\
                Tel : (+1) 410 338 4931\
                Fax : (+1) 410 338 4596\
                e-mail   : marel@stsci.edu\
                homepage : https://www.stsci.edu/~marel/
 
* Jos H. J. de Bruijne,

    >1994-1995 :\
        &emsp; testing and application of code\
    address   : Sterrewacht Leiden\
                Postbus 9513\
                2300 RA Leiden\
                The Netherlands\
                Tel : (+31) 71 5275878\
                Fax : (+31) 71 5275819\
                e-mail   : debruyne@strw.LeidenUniv.nl\
                homepage : http://www.strw.leidenuniv.nl/~debruyne/

* Eduardo Vitral,

    >2023-present :\
        &emsp; development of the Python interface\
        &emsp; implementation of plane-of-sky routines\
        &emsp; testing and application of code\
    address   : Royal Observatory of Edinburgh\
                Edinburgh, UK\
                e-mail   : eduardo.vitral@roe.ac.uk\
                homepage : https://eduardo-vitral.github.io

