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.
Files changed (42) hide show
  1. astro_species-4.0.0/.DS_Store +0 -0
  2. astro_species-4.0.0/.gitignore +21 -0
  3. astro_species-4.0.0/LICENSE.md +23 -0
  4. astro_species-4.0.0/PKG-INFO +265 -0
  5. astro_species-4.0.0/README.md +230 -0
  6. astro_species-4.0.0/pyproject.toml +57 -0
  7. astro_species-4.0.0/setup.cfg +4 -0
  8. astro_species-4.0.0/src/astro_species.egg-info/PKG-INFO +265 -0
  9. astro_species-4.0.0/src/astro_species.egg-info/SOURCES.txt +40 -0
  10. astro_species-4.0.0/src/astro_species.egg-info/dependency_links.txt +1 -0
  11. astro_species-4.0.0/src/astro_species.egg-info/entry_points.txt +2 -0
  12. astro_species-4.0.0/src/astro_species.egg-info/requires.txt +23 -0
  13. astro_species-4.0.0/src/astro_species.egg-info/top_level.txt +1 -0
  14. astro_species-4.0.0/src/species/__init__.py +22 -0
  15. astro_species-4.0.0/src/species/abundances.py +220 -0
  16. astro_species-4.0.0/src/species/analyzer.py +410 -0
  17. astro_species-4.0.0/src/species/atmosphere.py +924 -0
  18. astro_species-4.0.0/src/species/broadening.py +523 -0
  19. astro_species-4.0.0/src/species/ccf.py +232 -0
  20. astro_species-4.0.0/src/species/cli.py +418 -0
  21. astro_species-4.0.0/src/species/config.py +131 -0
  22. astro_species-4.0.0/src/species/data/ATLAS9_grid.pickle +0 -0
  23. astro_species-4.0.0/src/species/data/__init__.py +1 -0
  24. astro_species-4.0.0/src/species/data/linelists/linelist.dat +172 -0
  25. astro_species-4.0.0/src/species/data/linelists/linelist_vsini.dat +7 -0
  26. astro_species-4.0.0/src/species/data/linelists/lines_ab.dat +217 -0
  27. astro_species-4.0.0/src/species/data/masks/G2.mas +3625 -0
  28. astro_species-4.0.0/src/species/data/solar.py +57 -0
  29. astro_species-4.0.0/src/species/errors.py +336 -0
  30. astro_species-4.0.0/src/species/ew.py +631 -0
  31. astro_species-4.0.0/src/species/io/__init__.py +1 -0
  32. astro_species-4.0.0/src/species/io/plots.py +117 -0
  33. astro_species-4.0.0/src/species/io/results.py +128 -0
  34. astro_species-4.0.0/src/species/moog/__init__.py +13 -0
  35. astro_species-4.0.0/src/species/moog/atmosphere_grid.py +354 -0
  36. astro_species-4.0.0/src/species/moog/par_file.py +160 -0
  37. astro_species-4.0.0/src/species/moog/parser.py +276 -0
  38. astro_species-4.0.0/src/species/moog/wrapper.py +341 -0
  39. astro_species-4.0.0/src/species/photometry.py +196 -0
  40. astro_species-4.0.0/src/species/spectrum.py +575 -0
  41. astro_species-4.0.0/tests/__init__.py +0 -0
  42. 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
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+