Update from develop

.github/workflows/test.yml

@@ -34,6 +34,4 @@ jobs:
         pip install .
     - name: Test with pytest
       run: |
-        pytest tests/test_sfh.py tests/test_pipeline_module.py tests/test_run.py
-        # make test-units
-        # make test-notebooks
+        pytest tests/test_*

README.md

@@ -3,41 +3,126 @@
 [![Documentation Status](https://readthedocs.org/projects/besta/badge/?version=latest)](https://besta.readthedocs.io/en/latest/?badge=latest)
 [![test](https://github.com/PabloCorcho/besta/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/PabloCorcho/besta/actions/workflows/test.yml)
 
-BESTA is a Python package for inferring stellar population properties from spectroscopic and/or photometric data using Bayesian inference and Monte Carlo methods.
+BESTA is a Python library for Bayesian inference of galaxy stellar population properties from spectroscopic and/or photometric observations.
 
-Full documentation is available at [besta.readthedocs.io](https://besta.readthedocs.io).
+It provides a practical interface to build fitting workflows on top of:
 
-## Framework
+- [Population Synthesis Toolkit (PST)](https://github.com/paranoya/population-synthesis-toolkit) for stellar population modeling.
+- [CosmoSIS](https://cosmosis.readthedocs.io) for parameter estimation and sampling.
 
-BESTA is built on top of two core libraries:
+Full user and API documentation: [besta.readthedocs.io](https://besta.readthedocs.io)
 
-- **[Population Synthesis Toolkit (PST)](https://github.com/paranoya/population-synthesis-toolkit)** — flexible stellar population synthesis models.
-- **[CosmoSIS](https://cosmosis.readthedocs.io)** — modular parameter estimation via Monte Carlo sampling.
+## What BESTA Can Do
 
-## Features
+BESTA supports end-to-end stellar population fitting workflows, including:
 
-### Pipeline modules
+- Spectroscopic and photometric inference workflows.
+- Joint fitting of stellar population and kinematics.
+- Configurable star formation history (SFH) parameterizations.
+- Grid-based and emulator-based SFH inference options.
+- Sequential and batch execution of fitting pipelines.
+- Post-processing and visualization utilities for fitted solutions.
 
-Ready-to-use CosmoSIS pipeline modules are provided in `besta.pipeline_modules`:
+For detailed pipeline setup, module-level configuration, and examples, see the online documentation:
 
-| Module | Description |
-|---|---|
-| `GalaxySpectraModule` | Full spectroscopic SED fitting |
-| `FullSpectralFitModule` | Joint stellar population and kinematics fit from spectra |
-| `GalaxyPhotometryModule` | Broadband photometric SED fitting |
-| `SFHPhotometryGridModule` | SFH inference from photometry via model grid |
-| `SFHPhotometryEmulatorModule` | SFH inference from photometry via emulator |
+- [Quick guide](https://besta.readthedocs.io/en/latest/quick_guide.html)
+- [Configuration reference](https://besta.readthedocs.io/en/latest/configuration.html)
+- [Pipeline manager docs](https://besta.readthedocs.io/en/latest/manager.html)
+- [Tutorials](https://besta.readthedocs.io/en/latest/index.html)
 
-### Star formation history models
+## Installation
 
-Analytic: `ExponentialSFH`, `DelayedTauSFH`, `DelayedTauQuenchedSFH`, `LogNormalSFH`, `LogNormalQuenchedSFH`
+### Python version
 
-Piece-wise: `FixedTimeSFH`, `FixedTime_sSFR_SFH`, `FixedMassFracSFH`
+- `Python >= 3.10`
 
-## Installation
+### Install from PyPI
 
 ```bash
 pip install besta
 ```
 
-Requires Python ≥ 3.10. See the [installation guide](https://besta.readthedocs.io) for CosmoSIS setup instructions.
+### Install from source
+
+Depending on your platform and scientific Python installation, you may also need system libraries typically used by MPI and linear algebra backends (for example OpenMPI, BLAS/LAPACK, and a Fortran compiler).
+
+```bash
+git clone https://github.com/PabloCorcho/besta.git
+cd besta
+python -m pip install -r requirements.txt
+python -m pip install .
+```
+
+### Ubuntu/Debian example:
+
+```bash
+sudo apt update
+sudo apt install -y \
+	gfortran \
+	liblapack-dev \
+	libopenblas-dev \
+	openmpi-bin \
+	openmpi-common \
+	libopenmpi-dev \
+	libgtk2.0-dev
+```
+
+using conda
+
+```bash
+conda install -c conda-forge \
+    gcc_linux-64 \
+    gxx_linux-64 \
+    gfortran_linux-64 \
+    openmpi \
+    mpi4py \
+    gsl \
+    cfitsio \
+    fftw \
+    lapack \
+    openblas \
+    git \
+    make \
+    cmake \
+    pkg-config
+```
+
+Package names can vary by distribution and version. If your environment already provides BLAS/LAPACK and MPI through conda, you may not need to install all system-level packages.
+
+## Contributing
+
+Contributions are welcome, including bug fixes, new features, tests, docs, and tutorials.
+
+### Report issues
+
+- Open issues or feature requests at: [github.com/PabloCorcho/besta/issues](https://github.com/PabloCorcho/besta/issues)
+
+### Contribute code
+
+1. Fork the repository.
+2. Create a feature branch.
+3. Implement your changes and add or update tests.
+4. Update documentation when behavior or APIs change.
+5. Open a pull request with a clear summary and motivation.
+
+### Development quick start
+
+```bash
+git clone https://github.com/PabloCorcho/besta.git
+cd besta
+python -m pip install -r requirements.txt
+python -m pip install -e .
+pytest -q
+```
+
+## Citation
+
+If BESTA contributes to your research, please cite the project and acknowledge the software in your publication.
+
+## License
+
+BSD 3-Clause.
+
+## Contact
+
+For questions, please send an email to p.corcho.caballero@rug.nl

docs/requirements.txt

@@ -4,7 +4,7 @@ sphinx>=5.0.0
 nbsphinx>=0.9.3
 cosmosis
 astropy>=5.0.0
-numpy<2.0
+numpy
 matplotlib>=3.7.0
 extinction>=0.4
 scipy>=1.10

docs/source/configuration.rst

@@ -269,6 +269,9 @@ Photometry-only fit
    [runtime]
    sampler = maxlike
 
+   [maxlike]
+   method = Powell
+
    [output]
    filename = ./photometry_fit
    format = text
@@ -297,6 +300,13 @@ Single-spectrum fit
    [runtime]
    sampler = maxlike emcee
 
+   [maxlike]
+   method = Powell
+
+   [emcee]
+   nwalkers = 16
+   nsteps = 500
+
    [output]
    filename = ./spectral_fit
    format = text
@@ -334,6 +344,11 @@ spectra of the same galaxy simultaneously with shared parameters:
    from besta.pipeline_modules.full_spectral_fit import FullSpectralFitModule
 
    cfg = {
+
+      "runtime": {"sampler": "maxlike emcee"},
+         "maxlike": {"method": "Nelder-Mead", "tolerance": 1e-3, "maxiter": 3000},
+         "emcee": {"walkers": 32, "samples": 100, "nsteps": 100},
+
        "output": {"filename": "./fit_all", "format": "text"},
        "pipeline": {
            "modules": "FullSpectralFit_blue FullSpectralFit_red",

docs/source/grid.rst

@@ -4,40 +4,52 @@ Grid-Based Inference
 ====================
 
 BESTA includes a direct **model-grid inference** workflow that does not require
-CosmoSIS samplers. This mode is useful when you already have a finite model
-library and want fast posterior evaluation over that library.
-
-Why use the grid module instead of CosmoSIS sampling?
------------------------------------------------------
-
-Use the grid module when:
-
-- Your model space is already discretized (for example: precomputed SED/SSP libraries).
-- You want robust, repeatable inference with no MCMC tuning.
-- You need high throughput over many objects using candidate selection and parallel workers.
-- You want direct control over priors/likelihoods in Python.
-
-Prefer the CosmoSIS pipeline (see :ref:`pipeline_manager`) when:
-
-- Your parameter space is continuous and not naturally represented by a fixed grid.
-- You need sampler diagnostics and chain-level convergence checks.
-- You rely on existing module wiring in the CosmoSIS runtime.
-
+CosmoSIS samplers. This mode is particularly useful when you already have a finite model
+library and want fast posterior evaluation over that library or the volume of data very large.
 
 Core Concepts
 -------------
 
+The model-grid workflow is built around several key modules/classes:
+
 - :class:`besta.grid.grid.ModelGrid`: container for model observables/targets and metadata.
 - :class:`besta.grid.grid.GridFitter`: computes posterior weights over grid models.
 - :mod:`besta.grid.prob`: prior and likelihood building blocks.
 - :mod:`besta.grid.binning`: candidate selectors to avoid evaluating the full grid for every object.
 
+Working with ModelGrids
+-----------------------
+
+A :class:`~besta.grid.grid.ModelGrid` is a container of a grid of models split into ``observables`` and ``targets`` (see example below). They support multiple I/O formats:
+
+- FITS tables: :meth:`~besta.grid.grid.ModelGrid.from_fits_table`,
+  ``ModelGrid.to_fits_table(...)``
+- HDF5: :meth:`~besta.grid.grid.ModelGrid.from_hdf5`,
+  :meth:`~besta.grid.grid.ModelGrid.to_hdf5`
+- Pickle: :meth:`~besta.grid.grid.ModelGrid.from_pickle`,
+  :meth:`~besta.grid.grid.ModelGrid.to_pickle`
+- automatic loader: :meth:`~besta.grid.grid.ModelGrid.load_auto`
+
+Priors and Likelihoods
+----------------------
+
+The grid module is fully Bayesian; you choose the ingredients from
+:mod:`besta.grid.prob`:
+
+- priors: :class:`~besta.grid.prob.FlatPrior`, :class:`~besta.grid.prob.CompositePrior`,
+  :class:`~besta.grid.prob.ObservableDependentPrior`, and others,
+- likelihoods: :class:`~besta.grid.prob.GaussianProductLikelihood`,
+  :class:`~besta.grid.prob.CompositeLikelihood`, etc.
+
+This gives a similar statistical structure to sampling methods, but evaluated
+directly on a finite model set instead of drawing chains.
+
 
 Minimal Workflow
 ----------------
 
 1. Build or load a :class:`~besta.grid.grid.ModelGrid`.
-2. Create a :class:`~besta.grid.grid.GridFitter` with a likelihood and prior.
+2. Create a :class:`~besta.grid.grid.GridFitter` with a likelihood and a set of priors.
 3. Evaluate posterior summaries for one object, or run :meth:`~besta.grid.grid.GridFitter.fit_batch` for many.
 
 Example (single-object posterior on one target):
@@ -48,12 +60,12 @@ Example (single-object posterior on one target):
    from besta.grid import ModelGrid, GridFitter
    from besta.grid.prob import GaussianProductLikelihood, FlatPrior
 
-   # N models, P observables, Q targets
+   # N models, 3 observables, 4 targets
    grid = ModelGrid(
-       observables=obs_models,                # shape (N, P)
-       targets=target_models,                 # shape (N, Q)
+       observables=obs_models,                # shape (N, 3)
+       targets=target_models,                 # shape (N, 3)
        observable_names=["mag_g", "mag_r", "mag_i"],
-       target_names=["logM", "age", "Z", "z"],
+       target_names=["logM", "age", "Z", "z"],  # (stellar mass, mean age, metals, redshift)
    )
 
    fitter = GridFitter(
@@ -63,43 +75,45 @@ Example (single-object posterior on one target):
        use_standardised=True,
    )
 
-   x = np.array([22.1, 21.5, 21.2])          # observed data (P,)
-   sx = np.array([0.03, 0.03, 0.04])         # observational errors (P,)
+   x = np.array([22.1, 21.5, 21.2])          # observed data (3,)
+   sigma_x = np.array([0.03, 0.03, 0.04])         # observational errors (3,)
    bins = np.linspace(7.0, 12.0, 101)        # bins for logM
 
+   # Estimate the marginal stellar mass posterior PDF
    post_logM, centers = fitter.posterior_over_target(
        x_native=x,
-       sigma_native=sx,
-       target_col="logM",
+       sigma_native=sigma_x,
+       target_col="logM", 
        bins=bins,
    )
 
 
-Batch Inference (many objects)
-------------------------------
+Batch Inference
+----------------
 
-For catalogs, use :meth:`~besta.grid.grid.GridFitter.fit_batch`.
-It supports:
+For large samples, use :meth:`~besta.grid.grid.GridFitter.fit_batch`.
+This method supports:
 
 - optional candidate selection (`binner=`),
 - thread/process parallelism (`n_jobs`, `backend`),
 - posterior truncation controls (`posterior_keep_mass`, etc.),
 - optional per-target summary statistics (`stats_for`, `stats_bins`),
 - optional HDF5 output (`output_hdf5_path`).
 
+
 .. code-block:: python
 
    from besta.grid.binning import KDTreeBinner
 
-   binner = KDTreeBinner(dims=[0, 1, 2]).fit(grid)  # select candidates in observable space
+   binner = KDTreeBinner(dims=[0, 1, 2]).fit(grid)  # Use the first three observable columns
 
    results = fitter.fit_batch(
        X_native=X_catalog,                    # shape (M, P)
        SIG_native=SIG_catalog,                # shape (M, P)
        binner=binner,
        n_jobs=8,
        backend="thread",
-       stats_for=["logM", "age"],
+       stats_for=["logM", "age"],  # the posterior statistics for these two quantities
        stats_bins=[np.linspace(7, 12, 120), np.linspace(0, 14, 120)],
        output_hdf5_path="grid_fit_results.h5",
        output_hdf5_group="/run1",
@@ -111,39 +125,15 @@ It supports:
        pass
 
 
-Priors and Likelihoods
-----------------------
+Candidate selection
+^^^^^^^^^^^^^^^^^^^
 
-The grid module is fully Bayesian; you choose the ingredients from
-:mod:`besta.grid.prob`:
+This is an essential feature when it comes to using large high-dimensional model grids and large datasets. The binners act as model cadidate selectors, rather than using the entire grid on each evaluation, based on the observables of the input sources. This reduces significantly the number of posterior evaluations (sometimes by orders of magnitude).
 
-- priors: :class:`~besta.grid.prob.FlatPrior`, :class:`~besta.grid.prob.CompositePrior`,
-  :class:`~besta.grid.prob.ObservableDependentPrior`, and others,
-- likelihoods: :class:`~besta.grid.prob.GaussianProductLikelihood`,
-  :class:`~besta.grid.prob.CompositeLikelihood`, etc.
+Posterior analysis
+^^^^^^^^^^^^^^^^^^
 
-This gives a similar statistical structure to sampling methods, but evaluated
-directly on a finite model set instead of drawing chains.
-
-
-Input/Output and Reproducibility
---------------------------------
-
-:class:`~besta.grid.grid.ModelGrid` supports multiple formats:
-
-- FITS tables: :meth:`~besta.grid.grid.ModelGrid.from_fits_table`,
-  ``ModelGrid.to_fits_table(...)``
-- HDF5: :meth:`~besta.grid.grid.ModelGrid.from_hdf5`,
-  :meth:`~besta.grid.grid.ModelGrid.to_hdf5`
-- Pickle: :meth:`~besta.grid.grid.ModelGrid.from_pickle`,
-  :meth:`~besta.grid.grid.ModelGrid.to_pickle`
-- automatic loader: :meth:`~besta.grid.grid.ModelGrid.load_auto`
+BESTA includes some built-in tools for post-processing the posterior PDF and estimate several key quantities such as percentiles, MAP, or covariance matrix, per source.
 
 
-Practical Tips
---------------
 
-- Start with `FlatPrior + GaussianProductLikelihood` as a baseline.
-- If the grid is large, use a binner to cut candidate counts before posterior evaluation.
-- Use `return_mode="iter"` for low-memory streaming over large catalogs.
-- Write batch outputs to HDF5 for reproducible downstream post-processing.