astro-species 4.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- astro_species-4.0.0/.DS_Store +0 -0
- astro_species-4.0.0/.gitignore +21 -0
- astro_species-4.0.0/LICENSE.md +23 -0
- astro_species-4.0.0/PKG-INFO +265 -0
- astro_species-4.0.0/README.md +230 -0
- astro_species-4.0.0/pyproject.toml +57 -0
- astro_species-4.0.0/setup.cfg +4 -0
- astro_species-4.0.0/src/astro_species.egg-info/PKG-INFO +265 -0
- astro_species-4.0.0/src/astro_species.egg-info/SOURCES.txt +40 -0
- astro_species-4.0.0/src/astro_species.egg-info/dependency_links.txt +1 -0
- astro_species-4.0.0/src/astro_species.egg-info/entry_points.txt +2 -0
- astro_species-4.0.0/src/astro_species.egg-info/requires.txt +23 -0
- astro_species-4.0.0/src/astro_species.egg-info/top_level.txt +1 -0
- astro_species-4.0.0/src/species/__init__.py +22 -0
- astro_species-4.0.0/src/species/abundances.py +220 -0
- astro_species-4.0.0/src/species/analyzer.py +410 -0
- astro_species-4.0.0/src/species/atmosphere.py +924 -0
- astro_species-4.0.0/src/species/broadening.py +523 -0
- astro_species-4.0.0/src/species/ccf.py +232 -0
- astro_species-4.0.0/src/species/cli.py +418 -0
- astro_species-4.0.0/src/species/config.py +131 -0
- astro_species-4.0.0/src/species/data/ATLAS9_grid.pickle +0 -0
- astro_species-4.0.0/src/species/data/__init__.py +1 -0
- astro_species-4.0.0/src/species/data/linelists/linelist.dat +172 -0
- astro_species-4.0.0/src/species/data/linelists/linelist_vsini.dat +7 -0
- astro_species-4.0.0/src/species/data/linelists/lines_ab.dat +217 -0
- astro_species-4.0.0/src/species/data/masks/G2.mas +3625 -0
- astro_species-4.0.0/src/species/data/solar.py +57 -0
- astro_species-4.0.0/src/species/errors.py +336 -0
- astro_species-4.0.0/src/species/ew.py +631 -0
- astro_species-4.0.0/src/species/io/__init__.py +1 -0
- astro_species-4.0.0/src/species/io/plots.py +117 -0
- astro_species-4.0.0/src/species/io/results.py +128 -0
- astro_species-4.0.0/src/species/moog/__init__.py +13 -0
- astro_species-4.0.0/src/species/moog/atmosphere_grid.py +354 -0
- astro_species-4.0.0/src/species/moog/par_file.py +160 -0
- astro_species-4.0.0/src/species/moog/parser.py +276 -0
- astro_species-4.0.0/src/species/moog/wrapper.py +341 -0
- astro_species-4.0.0/src/species/photometry.py +196 -0
- astro_species-4.0.0/src/species/spectrum.py +575 -0
- astro_species-4.0.0/tests/__init__.py +0 -0
- astro_species-4.0.0/tests/test_smoke.py +286 -0
|
Binary file
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
__pycache__/
|
|
2
|
+
*.pyc
|
|
3
|
+
*.egg-info/
|
|
4
|
+
dist/
|
|
5
|
+
build/
|
|
6
|
+
.eggs/
|
|
7
|
+
*.egg
|
|
8
|
+
|
|
9
|
+
# IDE
|
|
10
|
+
.idea/
|
|
11
|
+
.vscode/
|
|
12
|
+
*.swp
|
|
13
|
+
.DS_Store
|
|
14
|
+
|
|
15
|
+
# Test / coverage
|
|
16
|
+
.pytest_cache/
|
|
17
|
+
htmlcov/
|
|
18
|
+
.coverage
|
|
19
|
+
|
|
20
|
+
# Raw ATLAS9 grids (pickle is bundled, raw files not needed)
|
|
21
|
+
atm_models/
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2017 Maritza Soto, James Jenkins
|
|
4
|
+
|
|
5
|
+
Copyright (c) 2026 Jose Vines
|
|
6
|
+
|
|
7
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
8
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
9
|
+
in the Software without restriction, including without limitation the rights
|
|
10
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
11
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
12
|
+
furnished to do so, subject to the following conditions:
|
|
13
|
+
|
|
14
|
+
The above copyright notice and this permission notice shall be included in all
|
|
15
|
+
copies or substantial portions of the Software.
|
|
16
|
+
|
|
17
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
18
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
19
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
20
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
21
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
22
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
23
|
+
SOFTWARE.
|
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: astro-species
|
|
3
|
+
Version: 4.0.0
|
|
4
|
+
Summary: SPECtroscopic Inference of stEllar parameterS
|
|
5
|
+
Author-email: Maritza Soto <marisotov@gmail.com>, Jose Vines <jose.vines@ug.uchile.cl>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Classifier: Development Status :: 3 - Alpha
|
|
8
|
+
Classifier: Intended Audience :: Science/Research
|
|
9
|
+
Classifier: Topic :: Scientific/Engineering :: Astronomy
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
12
|
+
Requires-Python: >=3.12
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE.md
|
|
15
|
+
Requires-Dist: numpy>=1.26
|
|
16
|
+
Requires-Dist: scipy>=1.12
|
|
17
|
+
Requires-Dist: odrpack>=0.5
|
|
18
|
+
Requires-Dist: astropy>=6.0
|
|
19
|
+
Requires-Dist: matplotlib>=3.8
|
|
20
|
+
Requires-Dist: pydantic>=2.5
|
|
21
|
+
Requires-Dist: pydantic-settings>=2.1
|
|
22
|
+
Requires-Dist: uncertainties>=3.1
|
|
23
|
+
Requires-Dist: PyAstronomy>=0.21
|
|
24
|
+
Provides-Extra: photometry
|
|
25
|
+
Requires-Dist: astroquery>=0.4.7; extra == "photometry"
|
|
26
|
+
Provides-Extra: cli
|
|
27
|
+
Requires-Dist: click>=8.1; extra == "cli"
|
|
28
|
+
Provides-Extra: test
|
|
29
|
+
Requires-Dist: pytest>=8.0; extra == "test"
|
|
30
|
+
Requires-Dist: pytest-cov; extra == "test"
|
|
31
|
+
Provides-Extra: dev
|
|
32
|
+
Requires-Dist: astro-species[cli,photometry,test]; extra == "dev"
|
|
33
|
+
Requires-Dist: ruff; extra == "dev"
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
|
|
36
|
+
# SPECIES v4
|
|
37
|
+
|
|
38
|
+
**SPECtroscopic Inference of stEllar parameterS**
|
|
39
|
+
|
|
40
|
+
A modern stellar spectroscopy pipeline for determining atmospheric parameters, chemical abundances, and broadening from high-resolution echelle spectra.
|
|
41
|
+
|
|
42
|
+
Originally created by Maritza Soto & James Jenkins ([Soto & Jenkins 2018](http://adsabs.harvard.edu/abs/2018A%26A...615A..76S)). Modernized and maintained by Jose Vines.
|
|
43
|
+
|
|
44
|
+
## What it does
|
|
45
|
+
|
|
46
|
+
Given a high-resolution stellar spectrum, SPECIES determines:
|
|
47
|
+
|
|
48
|
+
- **Atmospheric parameters**: Teff, log g, [Fe/H], microturbulence
|
|
49
|
+
- **Chemical abundances**: Na, Mg, Al, Si, Ca, Ti, Cr, Mn, Fe, Ni, Cu, Zn (14 ions)
|
|
50
|
+
- **Broadening**: vsini (rotational velocity) and vmac (macroturbulence)
|
|
51
|
+
|
|
52
|
+
It works by measuring equivalent widths of iron lines, then iteratively solving for the atmospheric parameters that produce excitation balance, ionization balance, and abundance consistency using MOOG (Sneden 1973) under the assumption of local thermodynamic equilibrium (LTE). Atmosphere models are interpolated from ATLAS9 grids (Castelli & Kurucz 2004).
|
|
53
|
+
|
|
54
|
+
## Installation
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pip install astro-species
|
|
58
|
+
species install-moog
|
|
59
|
+
species check
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`install-moog` downloads and compiles MOOG from source. You need `gfortran` installed:
|
|
63
|
+
|
|
64
|
+
| Platform | Command |
|
|
65
|
+
|----------|---------|
|
|
66
|
+
| Ubuntu/Debian | `sudo apt install gfortran` |
|
|
67
|
+
| Fedora/RHEL | `sudo dnf install gcc-gfortran` |
|
|
68
|
+
| macOS | `brew install gcc` |
|
|
69
|
+
| Conda | `conda install -c conda-forge gfortran` |
|
|
70
|
+
|
|
71
|
+
You also need ATLAS9 atmosphere model grids (~3.3 GB). These are not bundled with the package. Set `SPECIES_ATLAS9_DIR` to point to your local copy, or they will be downloaded on first use (TBD).
|
|
72
|
+
|
|
73
|
+
### Docker
|
|
74
|
+
|
|
75
|
+
For zero-setup usage:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
docker build -t species .
|
|
79
|
+
docker run -v ./spectra:/data species analyze /data/my_star.fits
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Quick start
|
|
83
|
+
|
|
84
|
+
### Python API
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
from species import Spectrum, Analyzer
|
|
88
|
+
|
|
89
|
+
# Load a spectrum (auto-detects instrument from FITS header)
|
|
90
|
+
spectrum = Spectrum.from_fits("my_star_feros.fits")
|
|
91
|
+
|
|
92
|
+
# Or from arrays (e.g. from your own reduction pipeline)
|
|
93
|
+
spectrum = Spectrum.from_arrays(wavelength, flux, snr=120, instrument="FEROS")
|
|
94
|
+
|
|
95
|
+
# Run the full analysis
|
|
96
|
+
result = Analyzer(spectrum).run()
|
|
97
|
+
|
|
98
|
+
# Results are structured Python objects
|
|
99
|
+
print(result.params.teff) # 5822.0
|
|
100
|
+
print(result.params.logg) # 4.52
|
|
101
|
+
print(result.params.feh) # -0.003
|
|
102
|
+
print(result.abundances["SiI"]) # ElementAbundance(abundance=+0.068, n_lines=20)
|
|
103
|
+
print(result.broadening.vsini) # 2.1 km/s
|
|
104
|
+
|
|
105
|
+
# Serialize
|
|
106
|
+
result.to_fits("results.fits")
|
|
107
|
+
result.to_dict() # for databases, JSON, etc.
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Batch processing
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
from pathlib import Path
|
|
114
|
+
from species import Spectrum, Analyzer
|
|
115
|
+
|
|
116
|
+
# Load multiple spectra
|
|
117
|
+
spectra = [Spectrum.from_fits(f) for f in Path("spectra/").glob("*.fits")]
|
|
118
|
+
|
|
119
|
+
# Analyze in parallel (4 cores)
|
|
120
|
+
results = Analyzer.batch(spectra, output_dir="./results", n_cores=4)
|
|
121
|
+
|
|
122
|
+
for result in results:
|
|
123
|
+
print(f"{result.star_name}: T={result.params.teff:.0f} [Fe/H]={result.params.feh:.3f}")
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Command line
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
# Single star
|
|
130
|
+
species analyze my_star.fits --output ./results
|
|
131
|
+
|
|
132
|
+
# Multiple stars
|
|
133
|
+
species analyze star1.fits star2.fits star3.fits --output ./results
|
|
134
|
+
|
|
135
|
+
# Glob pattern + parallel
|
|
136
|
+
species analyze spectra/*.fits --ncores 4
|
|
137
|
+
|
|
138
|
+
# Skip broadening (faster)
|
|
139
|
+
species analyze my_star.fits --no-broadening
|
|
140
|
+
|
|
141
|
+
# Giant star
|
|
142
|
+
species analyze my_star.fits --giant
|
|
143
|
+
|
|
144
|
+
# EW measurement only
|
|
145
|
+
species ew-only my_star.fits
|
|
146
|
+
|
|
147
|
+
# Check installation
|
|
148
|
+
species check
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Configuration
|
|
152
|
+
|
|
153
|
+
All settings can be overridden via environment variables or constructor arguments:
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
from species import Analyzer, Spectrum, Settings
|
|
157
|
+
|
|
158
|
+
config = Settings(
|
|
159
|
+
atlas9_dir="/path/to/grids",
|
|
160
|
+
moog_binary="/usr/local/bin/MOOGSILENT",
|
|
161
|
+
is_giant=True,
|
|
162
|
+
)
|
|
163
|
+
|
|
164
|
+
result = Analyzer(spectrum, config=config).run()
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Environment variables use the `SPECIES_` prefix: `SPECIES_ATLAS9_DIR`, `SPECIES_MOOG_BINARY`, etc.
|
|
168
|
+
|
|
169
|
+
## Supported instruments
|
|
170
|
+
|
|
171
|
+
SPECIES reads spectra from:
|
|
172
|
+
|
|
173
|
+
- **HARPS** (ESO 3.6m)
|
|
174
|
+
- **FEROS** (ESO/MPG 2.2m)
|
|
175
|
+
- **UVES** (ESO VLT)
|
|
176
|
+
- **HIRES** (Keck)
|
|
177
|
+
- **CORALIE** (Euler 1.2m)
|
|
178
|
+
- **PFS** (Magellan)
|
|
179
|
+
- **AAT**
|
|
180
|
+
- **LCO NRES**
|
|
181
|
+
- Generic FITS (auto-detected from WCS keywords or 2D data layout)
|
|
182
|
+
|
|
183
|
+
Instrument is auto-detected from the FITS header `INSTRUME` keyword or the filename convention (`starname_instrument.fits`). You can also pass `instrument="FEROS"` explicitly.
|
|
184
|
+
|
|
185
|
+
## Changes from the original SPECIES
|
|
186
|
+
|
|
187
|
+
### Algorithmic improvements
|
|
188
|
+
|
|
189
|
+
**Broyden's method replaces per-parameter bisection.** The original adjusted one parameter at a time (metallicity, then temperature, then gravity, then microturbulence) via bisection, cycling until all four diagnostics converged. This required 600-900 MOOG calls per star and had convergence issues when porting from Python 2 to 3 due to float comparison semantics. The new default uses Broyden's quasi-Newton method, which solves the 4-equation system simultaneously in 10-16 MOOG calls. The residual norm is typically 250x smaller. The old bisection method is still available via `method="per_parameter"`.
|
|
190
|
+
|
|
191
|
+
**Broadening uses MOOG 5x instead of 75x.** The original ran a separate MOOG synthesis for each vsini grid point (15 values x 5 lines = 75 calls). But the unbroadened spectrum is identical regardless of vsini — rotational broadening is applied afterward. The new code synthesizes once per diagnostic line and applies `pyasl.rotBroad()` in numpy.
|
|
192
|
+
|
|
193
|
+
**Error propagation unified.** The original had two nearly identical files (`CalcErrors_new.py` for dwarfs, `CalcErrorsGiant_new.py` for giants) differing only in polynomial coefficients. Now a single parameterized module.
|
|
194
|
+
|
|
195
|
+
### Architecture
|
|
196
|
+
|
|
197
|
+
| Aspect | Original (v3) | v4 |
|
|
198
|
+
|--------|--------------|-----|
|
|
199
|
+
| Python version | 2.7/3.x compatible | 3.12+ |
|
|
200
|
+
| Packaging | None (clone and run) | `pip install astro-species` |
|
|
201
|
+
| API | CLI only (`python SPECIES.py -starlist ...`) | Python library + CLI |
|
|
202
|
+
| Configuration | 80+ global variables, 40+ CLI flags | Pydantic Settings + env vars |
|
|
203
|
+
| MOOG interface | `os.system("MOOGSILENT")` | `subprocess.run()` with timeout, error handling |
|
|
204
|
+
| Type hints | None | Full coverage |
|
|
205
|
+
| Tests | None | 17 integration tests |
|
|
206
|
+
| Output | Text files at hardcoded paths | Structured dataclasses, FITS, ASCII |
|
|
207
|
+
| Parallelism | Per-star (`multiprocessing.Pool`) | Per-star + MOOGSession for per-call efficiency |
|
|
208
|
+
| Lines of code | ~9,800 | ~5,800 |
|
|
209
|
+
|
|
210
|
+
### What was removed
|
|
211
|
+
|
|
212
|
+
- **Isochrone fitting** (`FindIsochrones.py`): Mass, age, and radius determination is now handled by downstream tools (Lachesis). SPECIES focuses on spectroscopy.
|
|
213
|
+
- **Python 2 compatibility**: `from __future__` imports, `past.utils.old_div`, `builtins` shims.
|
|
214
|
+
- **MultiNest/emcee dependencies**: These were only used by the isochrone module.
|
|
215
|
+
- **`mwdust` dependency**: Extinction correction is handled elsewhere.
|
|
216
|
+
- **Full `PhotometricRelations_class.py`**: Replaced with a lightweight Vizier lookup for initial parameter guesses. With Broyden's method, initial guesses matter less.
|
|
217
|
+
|
|
218
|
+
### Performance
|
|
219
|
+
|
|
220
|
+
| Metric | Original | v4 |
|
|
221
|
+
|--------|----------|-----|
|
|
222
|
+
| MOOG calls per star | 600-900 | 15-25 |
|
|
223
|
+
| Wall-clock time | 10-20 min | ~1 min |
|
|
224
|
+
| Convergence residual | ~0.05 | ~0.0002 |
|
|
225
|
+
|
|
226
|
+
## Package structure
|
|
227
|
+
|
|
228
|
+
```
|
|
229
|
+
src/species/
|
|
230
|
+
__init__.py # Public API: Spectrum, Analyzer, Settings
|
|
231
|
+
config.py # Pydantic Settings (replaces global variables)
|
|
232
|
+
cli.py # Command-line interface
|
|
233
|
+
analyzer.py # Main orchestrator
|
|
234
|
+
spectrum.py # Spectrum loading + instrument readers
|
|
235
|
+
ccf.py # Cross-correlation for RV / rest-frame correction
|
|
236
|
+
ew.py # Equivalent width measurement
|
|
237
|
+
atmosphere.py # Atmospheric parameter fitting (Broyden + bisection)
|
|
238
|
+
errors.py # Error propagation (unified dwarf/giant)
|
|
239
|
+
abundances.py # Chemical abundance determination
|
|
240
|
+
broadening.py # vsini / vmac measurement
|
|
241
|
+
photometry.py # Vizier initial parameter estimation
|
|
242
|
+
moog/
|
|
243
|
+
wrapper.py # MOOG subprocess interface + MOOGSession
|
|
244
|
+
parser.py # MOOG output parsing
|
|
245
|
+
par_file.py # Parameter file generation
|
|
246
|
+
atmosphere_grid.py # ATLAS9 grid interpolation
|
|
247
|
+
io/
|
|
248
|
+
results.py # Result dataclasses + serialization
|
|
249
|
+
plots.py # Diagnostic plots
|
|
250
|
+
data/
|
|
251
|
+
linelists/ # Bundled iron + abundance line lists
|
|
252
|
+
masks/ # Binary masks for CCF
|
|
253
|
+
solar.py # Asplund 2009 solar abundances
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
## Citation
|
|
257
|
+
|
|
258
|
+
If you use SPECIES in your work, please cite:
|
|
259
|
+
|
|
260
|
+
- Soto & Jenkins 2018, A&A 615, A76 ([ADS](http://adsabs.harvard.edu/abs/2018A%26A...615A..76S))
|
|
261
|
+
- Soto et al. 2021, MNRAS 508, 1
|
|
262
|
+
|
|
263
|
+
## License
|
|
264
|
+
|
|
265
|
+
MIT
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
# SPECIES v4
|
|
2
|
+
|
|
3
|
+
**SPECtroscopic Inference of stEllar parameterS**
|
|
4
|
+
|
|
5
|
+
A modern stellar spectroscopy pipeline for determining atmospheric parameters, chemical abundances, and broadening from high-resolution echelle spectra.
|
|
6
|
+
|
|
7
|
+
Originally created by Maritza Soto & James Jenkins ([Soto & Jenkins 2018](http://adsabs.harvard.edu/abs/2018A%26A...615A..76S)). Modernized and maintained by Jose Vines.
|
|
8
|
+
|
|
9
|
+
## What it does
|
|
10
|
+
|
|
11
|
+
Given a high-resolution stellar spectrum, SPECIES determines:
|
|
12
|
+
|
|
13
|
+
- **Atmospheric parameters**: Teff, log g, [Fe/H], microturbulence
|
|
14
|
+
- **Chemical abundances**: Na, Mg, Al, Si, Ca, Ti, Cr, Mn, Fe, Ni, Cu, Zn (14 ions)
|
|
15
|
+
- **Broadening**: vsini (rotational velocity) and vmac (macroturbulence)
|
|
16
|
+
|
|
17
|
+
It works by measuring equivalent widths of iron lines, then iteratively solving for the atmospheric parameters that produce excitation balance, ionization balance, and abundance consistency using MOOG (Sneden 1973) under the assumption of local thermodynamic equilibrium (LTE). Atmosphere models are interpolated from ATLAS9 grids (Castelli & Kurucz 2004).
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pip install astro-species
|
|
23
|
+
species install-moog
|
|
24
|
+
species check
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
`install-moog` downloads and compiles MOOG from source. You need `gfortran` installed:
|
|
28
|
+
|
|
29
|
+
| Platform | Command |
|
|
30
|
+
|----------|---------|
|
|
31
|
+
| Ubuntu/Debian | `sudo apt install gfortran` |
|
|
32
|
+
| Fedora/RHEL | `sudo dnf install gcc-gfortran` |
|
|
33
|
+
| macOS | `brew install gcc` |
|
|
34
|
+
| Conda | `conda install -c conda-forge gfortran` |
|
|
35
|
+
|
|
36
|
+
You also need ATLAS9 atmosphere model grids (~3.3 GB). These are not bundled with the package. Set `SPECIES_ATLAS9_DIR` to point to your local copy, or they will be downloaded on first use (TBD).
|
|
37
|
+
|
|
38
|
+
### Docker
|
|
39
|
+
|
|
40
|
+
For zero-setup usage:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
docker build -t species .
|
|
44
|
+
docker run -v ./spectra:/data species analyze /data/my_star.fits
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Quick start
|
|
48
|
+
|
|
49
|
+
### Python API
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
from species import Spectrum, Analyzer
|
|
53
|
+
|
|
54
|
+
# Load a spectrum (auto-detects instrument from FITS header)
|
|
55
|
+
spectrum = Spectrum.from_fits("my_star_feros.fits")
|
|
56
|
+
|
|
57
|
+
# Or from arrays (e.g. from your own reduction pipeline)
|
|
58
|
+
spectrum = Spectrum.from_arrays(wavelength, flux, snr=120, instrument="FEROS")
|
|
59
|
+
|
|
60
|
+
# Run the full analysis
|
|
61
|
+
result = Analyzer(spectrum).run()
|
|
62
|
+
|
|
63
|
+
# Results are structured Python objects
|
|
64
|
+
print(result.params.teff) # 5822.0
|
|
65
|
+
print(result.params.logg) # 4.52
|
|
66
|
+
print(result.params.feh) # -0.003
|
|
67
|
+
print(result.abundances["SiI"]) # ElementAbundance(abundance=+0.068, n_lines=20)
|
|
68
|
+
print(result.broadening.vsini) # 2.1 km/s
|
|
69
|
+
|
|
70
|
+
# Serialize
|
|
71
|
+
result.to_fits("results.fits")
|
|
72
|
+
result.to_dict() # for databases, JSON, etc.
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Batch processing
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
from pathlib import Path
|
|
79
|
+
from species import Spectrum, Analyzer
|
|
80
|
+
|
|
81
|
+
# Load multiple spectra
|
|
82
|
+
spectra = [Spectrum.from_fits(f) for f in Path("spectra/").glob("*.fits")]
|
|
83
|
+
|
|
84
|
+
# Analyze in parallel (4 cores)
|
|
85
|
+
results = Analyzer.batch(spectra, output_dir="./results", n_cores=4)
|
|
86
|
+
|
|
87
|
+
for result in results:
|
|
88
|
+
print(f"{result.star_name}: T={result.params.teff:.0f} [Fe/H]={result.params.feh:.3f}")
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Command line
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
# Single star
|
|
95
|
+
species analyze my_star.fits --output ./results
|
|
96
|
+
|
|
97
|
+
# Multiple stars
|
|
98
|
+
species analyze star1.fits star2.fits star3.fits --output ./results
|
|
99
|
+
|
|
100
|
+
# Glob pattern + parallel
|
|
101
|
+
species analyze spectra/*.fits --ncores 4
|
|
102
|
+
|
|
103
|
+
# Skip broadening (faster)
|
|
104
|
+
species analyze my_star.fits --no-broadening
|
|
105
|
+
|
|
106
|
+
# Giant star
|
|
107
|
+
species analyze my_star.fits --giant
|
|
108
|
+
|
|
109
|
+
# EW measurement only
|
|
110
|
+
species ew-only my_star.fits
|
|
111
|
+
|
|
112
|
+
# Check installation
|
|
113
|
+
species check
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### Configuration
|
|
117
|
+
|
|
118
|
+
All settings can be overridden via environment variables or constructor arguments:
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
from species import Analyzer, Spectrum, Settings
|
|
122
|
+
|
|
123
|
+
config = Settings(
|
|
124
|
+
atlas9_dir="/path/to/grids",
|
|
125
|
+
moog_binary="/usr/local/bin/MOOGSILENT",
|
|
126
|
+
is_giant=True,
|
|
127
|
+
)
|
|
128
|
+
|
|
129
|
+
result = Analyzer(spectrum, config=config).run()
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Environment variables use the `SPECIES_` prefix: `SPECIES_ATLAS9_DIR`, `SPECIES_MOOG_BINARY`, etc.
|
|
133
|
+
|
|
134
|
+
## Supported instruments
|
|
135
|
+
|
|
136
|
+
SPECIES reads spectra from:
|
|
137
|
+
|
|
138
|
+
- **HARPS** (ESO 3.6m)
|
|
139
|
+
- **FEROS** (ESO/MPG 2.2m)
|
|
140
|
+
- **UVES** (ESO VLT)
|
|
141
|
+
- **HIRES** (Keck)
|
|
142
|
+
- **CORALIE** (Euler 1.2m)
|
|
143
|
+
- **PFS** (Magellan)
|
|
144
|
+
- **AAT**
|
|
145
|
+
- **LCO NRES**
|
|
146
|
+
- Generic FITS (auto-detected from WCS keywords or 2D data layout)
|
|
147
|
+
|
|
148
|
+
Instrument is auto-detected from the FITS header `INSTRUME` keyword or the filename convention (`starname_instrument.fits`). You can also pass `instrument="FEROS"` explicitly.
|
|
149
|
+
|
|
150
|
+
## Changes from the original SPECIES
|
|
151
|
+
|
|
152
|
+
### Algorithmic improvements
|
|
153
|
+
|
|
154
|
+
**Broyden's method replaces per-parameter bisection.** The original adjusted one parameter at a time (metallicity, then temperature, then gravity, then microturbulence) via bisection, cycling until all four diagnostics converged. This required 600-900 MOOG calls per star and had convergence issues when porting from Python 2 to 3 due to float comparison semantics. The new default uses Broyden's quasi-Newton method, which solves the 4-equation system simultaneously in 10-16 MOOG calls. The residual norm is typically 250x smaller. The old bisection method is still available via `method="per_parameter"`.
|
|
155
|
+
|
|
156
|
+
**Broadening uses MOOG 5x instead of 75x.** The original ran a separate MOOG synthesis for each vsini grid point (15 values x 5 lines = 75 calls). But the unbroadened spectrum is identical regardless of vsini — rotational broadening is applied afterward. The new code synthesizes once per diagnostic line and applies `pyasl.rotBroad()` in numpy.
|
|
157
|
+
|
|
158
|
+
**Error propagation unified.** The original had two nearly identical files (`CalcErrors_new.py` for dwarfs, `CalcErrorsGiant_new.py` for giants) differing only in polynomial coefficients. Now a single parameterized module.
|
|
159
|
+
|
|
160
|
+
### Architecture
|
|
161
|
+
|
|
162
|
+
| Aspect | Original (v3) | v4 |
|
|
163
|
+
|--------|--------------|-----|
|
|
164
|
+
| Python version | 2.7/3.x compatible | 3.12+ |
|
|
165
|
+
| Packaging | None (clone and run) | `pip install astro-species` |
|
|
166
|
+
| API | CLI only (`python SPECIES.py -starlist ...`) | Python library + CLI |
|
|
167
|
+
| Configuration | 80+ global variables, 40+ CLI flags | Pydantic Settings + env vars |
|
|
168
|
+
| MOOG interface | `os.system("MOOGSILENT")` | `subprocess.run()` with timeout, error handling |
|
|
169
|
+
| Type hints | None | Full coverage |
|
|
170
|
+
| Tests | None | 17 integration tests |
|
|
171
|
+
| Output | Text files at hardcoded paths | Structured dataclasses, FITS, ASCII |
|
|
172
|
+
| Parallelism | Per-star (`multiprocessing.Pool`) | Per-star + MOOGSession for per-call efficiency |
|
|
173
|
+
| Lines of code | ~9,800 | ~5,800 |
|
|
174
|
+
|
|
175
|
+
### What was removed
|
|
176
|
+
|
|
177
|
+
- **Isochrone fitting** (`FindIsochrones.py`): Mass, age, and radius determination is now handled by downstream tools (Lachesis). SPECIES focuses on spectroscopy.
|
|
178
|
+
- **Python 2 compatibility**: `from __future__` imports, `past.utils.old_div`, `builtins` shims.
|
|
179
|
+
- **MultiNest/emcee dependencies**: These were only used by the isochrone module.
|
|
180
|
+
- **`mwdust` dependency**: Extinction correction is handled elsewhere.
|
|
181
|
+
- **Full `PhotometricRelations_class.py`**: Replaced with a lightweight Vizier lookup for initial parameter guesses. With Broyden's method, initial guesses matter less.
|
|
182
|
+
|
|
183
|
+
### Performance
|
|
184
|
+
|
|
185
|
+
| Metric | Original | v4 |
|
|
186
|
+
|--------|----------|-----|
|
|
187
|
+
| MOOG calls per star | 600-900 | 15-25 |
|
|
188
|
+
| Wall-clock time | 10-20 min | ~1 min |
|
|
189
|
+
| Convergence residual | ~0.05 | ~0.0002 |
|
|
190
|
+
|
|
191
|
+
## Package structure
|
|
192
|
+
|
|
193
|
+
```
|
|
194
|
+
src/species/
|
|
195
|
+
__init__.py # Public API: Spectrum, Analyzer, Settings
|
|
196
|
+
config.py # Pydantic Settings (replaces global variables)
|
|
197
|
+
cli.py # Command-line interface
|
|
198
|
+
analyzer.py # Main orchestrator
|
|
199
|
+
spectrum.py # Spectrum loading + instrument readers
|
|
200
|
+
ccf.py # Cross-correlation for RV / rest-frame correction
|
|
201
|
+
ew.py # Equivalent width measurement
|
|
202
|
+
atmosphere.py # Atmospheric parameter fitting (Broyden + bisection)
|
|
203
|
+
errors.py # Error propagation (unified dwarf/giant)
|
|
204
|
+
abundances.py # Chemical abundance determination
|
|
205
|
+
broadening.py # vsini / vmac measurement
|
|
206
|
+
photometry.py # Vizier initial parameter estimation
|
|
207
|
+
moog/
|
|
208
|
+
wrapper.py # MOOG subprocess interface + MOOGSession
|
|
209
|
+
parser.py # MOOG output parsing
|
|
210
|
+
par_file.py # Parameter file generation
|
|
211
|
+
atmosphere_grid.py # ATLAS9 grid interpolation
|
|
212
|
+
io/
|
|
213
|
+
results.py # Result dataclasses + serialization
|
|
214
|
+
plots.py # Diagnostic plots
|
|
215
|
+
data/
|
|
216
|
+
linelists/ # Bundled iron + abundance line lists
|
|
217
|
+
masks/ # Binary masks for CCF
|
|
218
|
+
solar.py # Asplund 2009 solar abundances
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
## Citation
|
|
222
|
+
|
|
223
|
+
If you use SPECIES in your work, please cite:
|
|
224
|
+
|
|
225
|
+
- Soto & Jenkins 2018, A&A 615, A76 ([ADS](http://adsabs.harvard.edu/abs/2018A%26A...615A..76S))
|
|
226
|
+
- Soto et al. 2021, MNRAS 508, 1
|
|
227
|
+
|
|
228
|
+
## License
|
|
229
|
+
|
|
230
|
+
MIT
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68.0", "setuptools-scm>=8.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "astro-species"
|
|
7
|
+
version = "4.0.0"
|
|
8
|
+
description = "SPECtroscopic Inference of stEllar parameterS"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
requires-python = ">=3.12"
|
|
12
|
+
authors = [
|
|
13
|
+
{name = "Maritza Soto", email = "marisotov@gmail.com"},
|
|
14
|
+
{name = "Jose Vines", email = "jose.vines@ug.uchile.cl"},
|
|
15
|
+
]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 3 - Alpha",
|
|
18
|
+
"Intended Audience :: Science/Research",
|
|
19
|
+
"Topic :: Scientific/Engineering :: Astronomy",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
]
|
|
23
|
+
dependencies = [
|
|
24
|
+
"numpy>=1.26",
|
|
25
|
+
"scipy>=1.12",
|
|
26
|
+
"odrpack>=0.5",
|
|
27
|
+
"astropy>=6.0",
|
|
28
|
+
"matplotlib>=3.8",
|
|
29
|
+
"pydantic>=2.5",
|
|
30
|
+
"pydantic-settings>=2.1",
|
|
31
|
+
"uncertainties>=3.1",
|
|
32
|
+
"PyAstronomy>=0.21",
|
|
33
|
+
]
|
|
34
|
+
|
|
35
|
+
[project.optional-dependencies]
|
|
36
|
+
photometry = ["astroquery>=0.4.7"]
|
|
37
|
+
cli = ["click>=8.1"]
|
|
38
|
+
test = ["pytest>=8.0", "pytest-cov"]
|
|
39
|
+
dev = ["astro-species[photometry,cli,test]", "ruff"]
|
|
40
|
+
|
|
41
|
+
[project.scripts]
|
|
42
|
+
species = "species.cli:main"
|
|
43
|
+
|
|
44
|
+
[tool.setuptools.packages.find]
|
|
45
|
+
where = ["src"]
|
|
46
|
+
|
|
47
|
+
[tool.setuptools.package-data]
|
|
48
|
+
species = ["data/linelists/*.dat", "data/masks/*.mas", "data/*.pickle"]
|
|
49
|
+
|
|
50
|
+
[tool.pytest.ini_options]
|
|
51
|
+
testpaths = ["tests"]
|
|
52
|
+
addopts = "-v --tb=short"
|
|
53
|
+
markers = ["slow: marks tests as slow (requires MOOG + grid)"]
|
|
54
|
+
|
|
55
|
+
[tool.ruff]
|
|
56
|
+
target-version = "py312"
|
|
57
|
+
line-length = 100
|