synference 0.1.1__tar.gz → 0.1.2__tar.gz

{synference-0.1.1 → synference-0.1.2}/.gitignore

@@ -4,7 +4,6 @@ docs/source/_autosummary
 docs/source/auto_examples/
 docs/source/gen_modules/
 docs/source/sg_execution_times.rst
-
 # Python-generated files
 __pycache__/
 *.py[oc]
@@ -58,4 +57,5 @@ tests/test_grids/*
 !tests/test_libraries/sps_test_library.hdf5
 !docs/build/gfx
 !docs/source/example_models/BPASS_DB_v4/*
-!docs/source/example_libraries/*
+!docs/source/example_libraries/*
+!docs/source/gfx/*.png

{synference-0.1.1 → synference-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synference
-Version: 0.1.1
+Version: 0.1.2
 Summary: Simulation-based inference for SED-fitting of galaxy photometry and spectroscopy
 Project-URL: Homepage, https://github.com/synthesizer-project/synference
 Project-URL: Bug Reports, https://github.com/synthesizer-project/synference/issues

{synference-0.1.1 → synference-0.1.2}/docs/source/FAQ/FAQ.rst

@@ -43,10 +43,7 @@ This will load the model from the specified path and move it to the CPU for infe
 What other SBI tools are available for SED fitting and more generally for galaxy inference?
 --------------------------------------------------------------------------------------------
 
-There are a number of great tools out there for specific applications of SBI.
-This is not an exhaustive list (and feel free to suggest more), but below
-we've collated some of the useful tools we've found. Please cite the
-relevant papers if you use these tools. 
+There are a number of great tools out there for specific applications of SBI. This is not an exhaustive list (and feel free to suggest more), but below we've collated some of the useful tools we've found. Please cite the relevant papers if you use these tools. 
 
 1. `SBIPIX <https://github.com/patriglesias/SBIPIX/>`_ - Published
    `here <https://ui.adsabs.harvard.edu/abs/2025arXiv250604336I/abstract>`_.

synference-0.1.2/docs/source/advanced_topics/custom_loop.ipynb

@@ -0,0 +1,271 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "72b87783",
+   "metadata": {},
+   "source": [
+    "# Custom Training Loop\n",
+    "\n",
+    "Synference implements a custom training loop (within the `custom_runner.py` submodule) which offers more flexibility than the built-in training loops of `sbi` and `LtU-ILI`. This allows users to implement advanced training strategies, such as custom optimizers (e.g. AdamW), and several quality of life features, such as model caching during training to avoid losing progress in case of interruptions.\n",
+    "\n",
+    "Crucially, this custom training loop is also directly integrated with Optuna for hyperparameter optimization, allowing users to easily perform hyperparameter searches while training their models. It reports training progress to Optuna, allowing users to monitor the performance of different hyperparameter configurations in real-time, and allows pruning of unpromising trials based on intermediate results."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2843c835",
+   "metadata": {},
+   "source": [
+    "The interface to this is still in beta, and will be stabilized in future releases and brought into line with the rest of Synference's API.\n",
+    "\n",
+    "Currently the custom training loop is configured via a YAML configuration file, which specifies the training parameters, optimizer settings, and other options. An example configuration file is provided below:\n",
+    "\n",
+    "```yaml\n",
+    "\n",
+    "train_args:\n",
+    "  skip_optimization: True\n",
+    "  validation_fraction: 0.1\n",
+    "  fixed_params:\n",
+    "    model_choice: \"nsf\" # Must be a list\n",
+    "    optimizer_choice: \"Adam\" # Must be a list\n",
+    "    learning_rate: 0.0007460108070908076\n",
+    "    training_batch_size: 79\n",
+    "    stop_after_epochs: 57\n",
+    "    clip_max_norm: 6.656577606872957\n",
+    "    nsf_hidden_features: 30\n",
+    "    nsf_num_transforms: 14\n",
+    "\n",
+    "\n",
+    "```\n",
+    "\n",
+    "This configuration file does not perform optimization, but instead trains a model with specified hyperparameters. To perform hyperparameter optimization, an example configuration file is provided below:\n",
+    "\n",
+    "```yaml\n",
+    "\n",
+    "train_args:\n",
+    "  skip_optimization: False\n",
+    "  validation_fraction: 0.1\n",
+    "  optuna:\n",
+    "    n_trials: 50\n",
+    "    build_final_model: False\n",
+    "    objective:\n",
+    "      metric: 'log_prob'\n",
+    "    study:\n",
+    "      study_name: \"\"\n",
+    "      storage: \"\"\n",
+    "      direction: 'maximize'\n",
+    "      load_if_exists: True\n",
+    "    pruner:\n",
+    "      type: Median\n",
+    "      n_startup_trials: 10\n",
+    "      n_warmup_steps: 30\n",
+    "      interval_steps: 10\n",
+    "      n_min_trials: 10\n",
+    "      #max_resource: 1000\n",
+    "      #reduction_factor: 3\n",
+    "      #min_resource: 10\n",
+    "      #bootstrap_count: 10\n",
+    "    search_space:\n",
+    "      model_choice: [\"mdn\", \"nsf\"] # Must be a list\n",
+    "      optimizer_choice: [\"AdamW\", \"Adam\"] # Must be a list\n",
+    "      learning_rate:\n",
+    "        type: \"float\"\n",
+    "        low: 1e-6\n",
+    "        high: 5e-2\n",
+    "        log: True\n",
+    "      training_batch_size:\n",
+    "        type: \"int\"\n",
+    "        low: 32\n",
+    "        high: 256\n",
+    "      stop_after_epochs:\n",
+    "        type: \"int\"\n",
+    "        low: 10\n",
+    "        high: 60\n",
+    "      clip_max_norm:\n",
+    "        type: \"float\"\n",
+    "        low: 0.1\n",
+    "        high: 10.0\n",
+    "      models:\n",
+    "        nsf: \n",
+    "          hidden_features:\n",
+    "            type: \"int\"\n",
+    "            low: 10\n",
+    "            high: 100\n",
+    "          num_transforms:\n",
+    "            type: \"int\"\n",
+    "            low: 3\n",
+    "            high: 128\n",
+    "        mdn: \n",
+    "          hidden_features:\n",
+    "            type: \"int\"\n",
+    "            low: 10\n",
+    "            high: 200\n",
+    "          num_components:\n",
+    "            type: \"int\"\n",
+    "            low: 10\n",
+    "            high: 600\n",
+    "\n",
+    "```\n",
+    "\n",
+    "\n",
+    "This configuration file will perform hyperparameter optimization over the specified search space, using the median pruner to prune unpromising trials. The objective metric is set to 'log_prob', meaning that the optimization will aim to maximize the log probability of the validation data under the trained model.\n",
+    "\n",
+    "If you are performing optimization parallelized across multiple nodes, you will probably  want to run an external SQL database which supports concurrent connections, such as PostgreSQL or MySQL, and provide the appropriate connection string in the `storage` field of the `study` section of the configuration file, or directly via the `sql_db_path` argument of the `run_single_sbi()` method."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3145980e",
+   "metadata": {},
+   "source": [
+    "```python\n",
+    "\n",
+    "fitter.run_single_sbi(...,\n",
+    "    custom_config_yaml=\"path/to/custom_config.yaml\",\n",
+    "    sql_db_path='mysql+pymysql://root:password@url:port/study_name'\n",
+    ")\n",
+    "\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6261165f",
+   "metadata": {},
+   "source": [
+    "We recommend [Optuna Dashboard](https://optuna-dashboard.readthedocs.io/en/latest/getting-started.html) for monitoring the progress of hyperparameter optimization. This can be launched using the following command:\n",
+    "\n",
+    "```bash\n",
+    "optuna-dashboard your_sql_link\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cc76e813",
+   "metadata": {},
+   "source": [
+    "## Custom Loop with a Fixed Model\n",
+    "\n",
+    "You can also use the custom training loop to train models with fixed parameter values, with a different configuration. This lets you take advantage of the additional features such as the customizable optimizer, model training checkpoints and ongoing training monitoring.\n",
+    "\n",
+    "Here is an example of the yaml file to train a specific fixed model, in this case a Neural Spline Flow, using the Adam optimizer, with 30 hidden features and 14 transforms."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cb63e847",
+   "metadata": {},
+   "source": [
+    "```yaml\n",
+    "train_args:\n",
+    "  skip_optimization: True\n",
+    "  validation_fraction: 0.1\n",
+    "  fixed_params:\n",
+    "    model_choice: \"nsf\" # Must be a list\n",
+    "    optimizer_choice: \"Adam\" # Must be a list\n",
+    "    learning_rate: 0.0007460108070908076\n",
+    "    training_batch_size: 79\n",
+    "    stop_after_epochs: 57\n",
+    "    clip_max_norm: 6.656577606872957\n",
+    "    nsf_hidden_features: 30\n",
+    "    nsf_num_transforms: 14\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "be69d999",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "config = {\n",
+    "    \"train_args\": {\n",
+    "        \"skip_optimization\": True,\n",
+    "        \"validation_fraction\": 0.1,\n",
+    "        \"fixed_params\": {\n",
+    "            \"model_choice\": \"nsf\",\n",
+    "            \"optimizer_choice\": \"Adam\",\n",
+    "            \"learning_rate\": 0.0007460108070908076,\n",
+    "            \"training_batch_size\": 79,\n",
+    "            \"stop_after_epochs\": 57,\n",
+    "            \"clip_max_norm\": 6.656577606872957,\n",
+    "            \"nsf_hidden_features\": 30,\n",
+    "            \"nsf_num_transforms\": 14,\n",
+    "        },\n",
+    "    }\n",
+    "}\n",
+    "\n",
+    "import yaml\n",
+    "\n",
+    "with open(\"config.yaml\", \"w\") as f:\n",
+    "    yaml.dump(config, f)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "29780005",
+   "metadata": {},
+   "source": [
+    "First we initialize a pre-configured model library."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0ca21ae1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from synference import SBI_Fitter, test_data_dir\n",
+    "\n",
+    "fitter = SBI_Fitter.init_from_hdf5(\n",
+    "    model_name=\"test\", hdf5_path=f\"{test_data_dir}/example_model_library.hdf5\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "00dae994",
+   "metadata": {},
+   "source": [
+    "Then we create our training arrays."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "89b72d4c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fitter.create_feature_array();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "429f7303",
+   "metadata": {},
+   "source": [
+    "Now we can train a model - note that this is a terrible model with far too small a dataset, purely for demonstration purposes.\n",
+    "\n",
+    "The plotted live training loss curves look slightly odd in a notebook format, but you can see the live progress of your model on your training and validation set, and see where the best performing training epoch is."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7d8c65ce",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fitter.run_single_sbi(custom_config_yaml=\"config.yaml\")"
+   ]
+  }
+ ],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{synference-0.1.1 → synference-0.1.2}/docs/source/index.rst

@@ -32,10 +32,29 @@ Contents
 Citation & Acknowledgement
 --------------------------
 
-Please cite **all** of the following papers if you use Synference in your research. Harvey et al. 2025 (in prep.) introduces the Synference code, `Lovell et al. 2025 <https://ui.adsabs.harvard.edu/abs/2025arXiv250803888L/abstract>`_ & `Roper et al. 2025 <https://ui.adsabs.harvard.edu/abs/2025arXiv250615811R/abstract>`_ introduce the Synthesizer code, and `Ho et al. 2024 <https://ui.adsabs.harvard.edu/abs/2024OJAp....7E..54H/abstract>`_ introduces the LtU-ILI framework.
+Please cite **all** of the following papers if you use Synference in your research. `Harvey et al. 2026 <https://arxiv.org/abs/2511.10640>`_ introduces the Synference code, `Lovell et al. 2025 <https://ui.adsabs.harvard.edu/abs/2025arXiv250803888L/abstract>`_ & `Roper et al. 2026 <https://ui.adsabs.harvard.edu/abs/2025arXiv250615811R/abstract>`_ introduce the Synthesizer code, and `Ho et al. 2024 <https://ui.adsabs.harvard.edu/abs/2024OJAp....7E..54H/abstract>`_ introduces the LtU-ILI framework.
 
 .. code-block:: bibtex
 
+      @ARTICLE{2026MNRAS.547ag282H,
+             author = {{Harvey}, Thomas and {Lovell}, Christopher C. and {Newman}, Sophie and {Conselice}, Christopher J. and {Austin}, Duncan and {Roper}, William J. and {Vijayan}, Aswin P. and {Wilkins}, Stephen M. and {Iglesias-Navarro}, Patricia and {Rusakov}, Vadim and {Li}, Qiong and {Adams}, Nathan and {Magdwick}, Kai and {Goolsby}, Caio M. and {Huertas-Company}, Marc and {Ho}, Matthew},
+              title = "{Flexible simulation-based inference for galaxy photometric fitting with synthesizer}",
+            journal = {\mnras},
+           keywords = {methods: data analysis, techniques: photometric, galaxies: photometry, galaxies: stellar content, Astrophysics of Galaxies, Cosmology and Nongalactic Astrophysics, Instrumentation and Methods for Astrophysics},
+               year = 2026,
+              month = mar,
+             volume = {547},
+             number = {1},
+                eid = {stag282},
+              pages = {stag282},
+                doi = {10.1093/mnras/stag282},
+      archivePrefix = {arXiv},
+             eprint = {2511.10640},
+       primaryClass = {astro-ph.GA},
+             adsurl = {https://ui.adsabs.harvard.edu/abs/2026MNRAS.547ag282H},
+            adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+      }
+
       @ARTICLE{2025OJAp....8E.152L,
             author = {{Lovell}, Christopher C. and {Roper}, William J. and {Vijayan}, Aswin P. and {Wilkins}, Stephen M. and {Newman}, Sophie and {Seeyave}, Louise},
             title = "{Synthesizer: a Software Package for Synthetic Astronomical Observables}",
@@ -54,19 +73,22 @@ Please cite **all** of the following papers if you use Synference in your resear
             adsnote = {Provided by the SAO/NASA Astrophysics Data System}
       }
 
-      @ARTICLE{2025arXiv250615811R,
-         author = {{Roper}, Will J. and {Lovell}, Christopher and {Vijayan}, Aswin and {Wilkins}, Stephen and {Akins}, Hollis and {Berger}, Sabrina and {Sant Fournier}, Connor and {Harvey}, Thomas and {Iyer}, Kartheik and {Leonardi}, Marco and {Newman}, Sophie and {Pautasso}, Borja and {Perry}, Ashley and {Seeyave}, Louise and {Sommovigo}, Laura},
-          title = "{Synthesizer: Synthetic Observables For Modern Astronomy}",
-        journal = {arXiv e-prints},
-       keywords = {Instrumentation and Methods for Astrophysics, Astrophysics of Galaxies},
-           year = 2025,
-          month = jun,
-            eid = {arXiv:2506.15811},
-          pages = {arXiv:2506.15811},
+      @ARTICLE{2026JOSS...11.9436R,
+             author = {{Roper}, Will and {Lovell}, Christopher and {Vijayan}, Aswin and {Wilkins}, Stephen and {Akins}, Hollis and {Berger}, Sabrina and {Sant Fournier}, Connor and {Harvey}, Thomas and {Iyer}, Kartheik and {Leonardi}, Marco and {Newman}, Sophie and {Pautasso}, Borja and {Perry}, Ashley and {Seeyave}, Louise and {Sommovigo}, Laura and {Punyasheel}, Paurush and {Aufan Stoffels d'Hautefort}, Adrien and {Rawlings}, Alex},
+              title = "{Synthesizer: Synthetic Observables for Modern Astronomy}",
+            journal = {The Journal of Open Source Software},
+           keywords = {astronomy, astrophysics, forward modelling, simulations, Python, C++, C, Instrumentation and Methods for Astrophysics, Astrophysics of Galaxies},
+               year = 2026,
+              month = mar,
+             volume = {11},
+             number = {119},
+                eid = {9436},
+              pages = {9436},
+                doi = {10.21105/joss.09436},
       archivePrefix = {arXiv},
              eprint = {2506.15811},
        primaryClass = {astro-ph.IM},
-             adsurl = {https://ui.adsabs.harvard.edu/abs/2025arXiv250615811R},
+             adsurl = {https://ui.adsabs.harvard.edu/abs/2026JOSS...11.9436R},
             adsnote = {Provided by the SAO/NASA Astrophysics Data System}
       }
 
@@ -100,4 +122,4 @@ Primary Contributors
 License
 -------
 
-Synference is free software made available under the GNU General Public License v3.0. For details see the `LICENSE <https://github.com/synthesizer-project/synference/blob/main/LICENSE.md>`_.
+Synference is free software made available under the GNU General Public License v3.0. For details see the `LICENSE <https://github.com/synthesizer-project/synference/blob/main/LICENSE.md>`_.

{synference-0.1.1 → synference-0.1.2}/docs/source/library_gen/basic_library_generation.ipynb

@@ -517,11 +517,7 @@
    ]
   }
  ],
- "metadata": {
-  "language_info": {
-   "name": "python"
-  }
- },
+ "metadata": {},
  "nbformat": 4,
  "nbformat_minor": 5
 }

{synference-0.1.1 → synference-0.1.2}/docs/source/library_gen/bring_your_own_library.ipynb

@@ -267,11 +267,7 @@
    ]
   }
  ],
- "metadata": {
-  "language_info": {
-   "name": "python"
-  }
- },
+ "metadata": {},
  "nbformat": 4,
  "nbformat_minor": 5
 }