diff --git a/docs/conf.py b/docs/conf.py index 085e3c439..3f70babd7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -74,7 +74,7 @@ # -- Options for Markdown files ---------------------------------------------- -myst_enable_extensions = ["colon_fence", "deflist"] +myst_enable_extensions = ["colon_fence", "deflist", "substitution"] myst_heading_anchors = 3 autosummary_generate = True diff --git a/docs/general/citations.md b/docs/general/citations.md new file mode 100644 index 000000000..09af11516 --- /dev/null +++ b/docs/general/citations.md @@ -0,0 +1,44 @@ +(references)= + +# Citations & References + +The bibtex entries for **PyAutoGalaxy** and its affiliated software packages can be found +[here](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/files/citations.bib), with example text for citing **PyAutoGalaxy** +in [.tex format here](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/files/citations.tex) format here and +[.md format here](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/files/citations.md). + +**PyAutoGalaxy** is published in the [Journal of Open Source Software](https://joss.theoj.org/papers/10.21105/joss.04475#) and its +entry in the above .bib file is under the citation key `pyautogalaxy`. + +As shown in the examples, we would greatly appreciate it if you mention **PyAutoGalaxy** by name and include a link to +our GitHub page! + +You should also specify the non-linear search(es) you use in your analysis (e.g. Dynesty, Emcee, PySwarms, etc) in +the main body of text, and delete as appropriate any packages your analysis did not use. The citations.bib file includes +the citation key for all of these projects. + +## Jax-Zero-Contour + +If you use the zero-contour method for critical curve and caustic computation (the default in +`visualize/general.yaml` via `critical_curves_method: zero_contour`), please cite the +`Jax-Zero-Contour` package by Coleman Krawczyk: + +```bibtex +@software{coleman_krawczyk_2025_15730415, + author = {Coleman Krawczyk}, + title = {CKrawczyk/Jax-Zero-Contour: Version 2.0.0}, + month = jun, + year = 2025, + publisher = {Zenodo}, + version = {v2.0.0}, + doi = {10.5281/zenodo.15730415}, + url = {https://doi.org/10.5281/zenodo.15730415}, +} +``` + +The package is available at and archived at +. + +## Dynesty + +If you used the nested sampling algorithm Dynesty, please follow the citation instructions [on the dynesty readthedocs](https://dynesty.readthedocs.io/en/latest/references.html). diff --git a/docs/general/citations.rst b/docs/general/citations.rst deleted file mode 100644 index 4aaa32222..000000000 --- a/docs/general/citations.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _references: - -Citations & References -====================== - -The bibtex entries for **PyAutoGalaxy** and its affiliated software packages can be found -`here `_, with example text for citing **PyAutoGalaxy** -in `.tex format here `_ format here and -`.md format here `_. - -**PyAutoGalaxy** is published in the `Journal of Open Source Software `_ and its -entry in the above .bib file is under the citation key ``pyautogalaxy``. - -As shown in the examples, we would greatly appreciate it if you mention **PyAutoGalaxy** by name and include a link to -our GitHub page! - -You should also specify the non-linear search(es) you use in your analysis (e.g. Dynesty, Emcee, PySwarms, etc) in -the main body of text, and delete as appropriate any packages your analysis did not use. The citations.bib file includes -the citation key for all of these projects. - -Jax-Zero-Contour ----------------- - -If you use the zero-contour method for critical curve and caustic computation (the default in -``visualize/general.yaml`` via ``critical_curves_method: zero_contour``), please cite the -``Jax-Zero-Contour`` package by Coleman Krawczyk: - -.. code-block:: bibtex - - @software{coleman_krawczyk_2025_15730415, - author = {Coleman Krawczyk}, - title = {CKrawczyk/Jax-Zero-Contour: Version 2.0.0}, - month = jun, - year = 2025, - publisher = {Zenodo}, - version = {v2.0.0}, - doi = {10.5281/zenodo.15730415}, - url = {https://doi.org/10.5281/zenodo.15730415}, - } - -The package is available at https://github.com/CKrawczyk/Jax-Zero-Contour and archived at -https://doi.org/10.5281/zenodo.15730415. - -Dynesty -------- - -If you used the nested sampling algorithm Dynesty, please follow the citation instructions `on the dynesty readthedocs `_. \ No newline at end of file diff --git a/docs/general/configs.md b/docs/general/configs.md new file mode 100644 index 000000000..9fff9ebb1 --- /dev/null +++ b/docs/general/configs.md @@ -0,0 +1,24 @@ +# Configs + +**PyAutoGalaxy** uses a number of configuration files that customize the default behaviour of the non-linear searches, +visualization and other aspects of **PyAutoGalaxy**. + +Descriptions of every configuration file and their input parameters are provided in the `README.rst` in +the [config directory of the workspace](https://github.com/Jammy2211/autogalaxy_workspace/tree/release/config) + +## Setup + +By default, **PyAutoGalaxy** looks for the config files in a `config` folder in the current working directory, which is +why we run autogalaxy scripts from the `autogalaxy_workspace` directory. + +The configuration path can also be set manually in a script using the project **PyAutoConf** and the following +command (the path to the `output` folder where the results of a non-linear search are stored is also set below): + +```bash +from autoconf import conf + +conf.instance.push( + config_path="path/to/config", + output_path=f"path/to/output" +) +``` diff --git a/docs/general/configs.rst b/docs/general/configs.rst deleted file mode 100644 index 56f936b43..000000000 --- a/docs/general/configs.rst +++ /dev/null @@ -1,27 +0,0 @@ -Configs -======= - -**PyAutoGalaxy** uses a number of configuration files that customize the default behaviour of the non-linear searches, -visualization and other aspects of **PyAutoGalaxy**. - -Descriptions of every configuration file and their input parameters are provided in the ``README.rst`` in -the `config directory of the workspace `_ - - -Setup ------ - -By default, **PyAutoGalaxy** looks for the config files in a ``config`` folder in the current working directory, which is -why we run autogalaxy scripts from the ``autogalaxy_workspace`` directory. - -The configuration path can also be set manually in a script using the project **PyAutoConf** and the following -command (the path to the ``output`` folder where the results of a non-linear search are stored is also set below): - -.. code-block:: bash - - from autoconf import conf - - conf.instance.push( - config_path="path/to/config", - output_path=f"path/to/output" - ) diff --git a/docs/general/credits.md b/docs/general/credits.md new file mode 100644 index 000000000..6fdd4dc2a --- /dev/null +++ b/docs/general/credits.md @@ -0,0 +1,33 @@ +(credits)= + +# Credits + +**Developers**: + +[James Nightingale](https://github.com/Jammy2211): Lead developer & PyAutoGalaxy guru. + +[Richard Hayes](https://github.com/rhayes777): Lead developer & [PyAutoFit](https://github.com/rhayes777/PyAutoFit) guru. + +[Aristeidis Amvrosiadis](https://github.com/Sketos): Interferometer Analysis. + +[Amy Etherington](https://github.com/amyetherington) : Magnification, Critical Curves and Caustic Calculations. + +Qiuhan He: NFW Profile Lensing Calculations. + +[Johnathan Frawley](https://github.com/jonathanfrawley): Profiling, optimization and build server tools. + +[Ashley Kelly](https://github.com/AshKelly): Developer of [pyquad](https://github.com/AshKelly/pyquad) for fast deflections computations. + +[Xiaoyue Cao](https://github.com/caoxiaoyue): Analytic Ellipitcal Power-Law Deflection Angle Calculations. + +[Nan Li](https://github.com/linan7788626): Docker integration & support. + +**Code Donors**: + +[Andrew Robertson](https://github.com/Andrew-Robertson): Critical curve & caustic calculations. + +Mattia Negrello: Visibility models in the uv-plane via direct Fourier transforms. + +[Andrea Enia](https://github.com/AndreaEnia): Voronoi source-plane plotting tools. + +Conor O'Riordan : Broken Power-Law mass profile. diff --git a/docs/general/credits.rst b/docs/general/credits.rst deleted file mode 100644 index 48d2264c5..000000000 --- a/docs/general/credits.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. _credits: - - -Credits -------- - -**Developers**: - -`James Nightingale `_: Lead developer & PyAutoGalaxy guru. - -`Richard Hayes `_: Lead developer & `PyAutoFit `_ guru. - -`Aristeidis Amvrosiadis `_: Interferometer Analysis. - -`Amy Etherington `_ : Magnification, Critical Curves and Caustic Calculations. - -Qiuhan He: NFW Profile Lensing Calculations. - -`Johnathan Frawley `_: Profiling, optimization and build server tools. - -`Ashley Kelly `_: Developer of `pyquad `_ for fast deflections computations. - -`Xiaoyue Cao `_: Analytic Ellipitcal Power-Law Deflection Angle Calculations. - -`Nan Li `_: Docker integration & support. - -**Code Donors**: - -`Andrew Robertson `_: Critical curve & caustic calculations. - -Mattia Negrello: Visibility models in the uv-plane via direct Fourier transforms. - -`Andrea Enia `_: Voronoi source-plane plotting tools. - -Conor O'Riordan : Broken Power-Law mass profile. diff --git a/docs/general/likelihood_function.rst b/docs/general/likelihood_function.md similarity index 67% rename from docs/general/likelihood_function.rst rename to docs/general/likelihood_function.md index e9793bcdb..d0f445b4c 100644 --- a/docs/general/likelihood_function.rst +++ b/docs/general/likelihood_function.md @@ -1,21 +1,20 @@ -.. _likelihood_function: - -Likelihood Function -=================== - -The ``autogalaxy_workspace`` contains Jupyter notebooks describing the (log) likelihood functions used by **PyAutoGalaxy**. - -The notebooks provide a step-by-step guide of how **PyAutoGalaxy** fits galaxy data, with the aim to make -the analysis clear to readers without background experience in galaxy modeling and make the modeling less -of a "black box". - -We recommend that when writing a paper using **PyAutoGalaxy** the author links to this GitHub repository when describing -their likelihood function. - -Links to every notebook are provided at the GitHub repository linked to below. We recommend authors link to this -GitHub repository (as opposed to direct links to each) because the URLs to notebooks on the ``autogalaxy_workspace`` -may change after papers are published. - -By linking to this repository a permanent URL is provided. - -https://github.com/Jammy2211/autogalaxy_likelihood_function \ No newline at end of file +(likelihood-function)= + +# Likelihood Function + +The `autogalaxy_workspace` contains Jupyter notebooks describing the (log) likelihood functions used by **PyAutoGalaxy**. + +The notebooks provide a step-by-step guide of how **PyAutoGalaxy** fits galaxy data, with the aim to make +the analysis clear to readers without background experience in galaxy modeling and make the modeling less +of a "black box". + +We recommend that when writing a paper using **PyAutoGalaxy** the author links to this GitHub repository when describing +their likelihood function. + +Links to every notebook are provided at the GitHub repository linked to below. We recommend authors link to this +GitHub repository (as opposed to direct links to each) because the URLs to notebooks on the `autogalaxy_workspace` +may change after papers are published. + +By linking to this repository a permanent URL is provided. + + diff --git a/docs/general/model_cookbook.md b/docs/general/model_cookbook.md new file mode 100644 index 000000000..b6b60bf57 --- /dev/null +++ b/docs/general/model_cookbook.md @@ -0,0 +1,268 @@ +(model-cookbook)= + +# Model Cookbook + +The model cookbook provides a concise reference to model composition tools, specifically the `Model` +and `Collection` objects. + +Examples using different **PyAutoGalaxy** API’s for model composition are provided, which produce more concise and +readable code for different use-cases. + +## Simple Model + +A simple model we can compose has a galaxy with a Sersic light profile: + +```python +bulge = af.Model(ag.lp.Sersic) + +galaxy = af.Model(ag.Galaxy, redshift=0.5, bulge=bulge) + +model = af.Collection(galaxies=af.Collection(galaxy=galaxy)) +``` + +The model `total_free_parameters` tells us the total number of free parameters (which are fitted for via a +non-linear search), which in this case is 7. + +```python +print(f"Model Total Free Parameters = {model.total_free_parameters}") +``` + +If we print the `info` attribute of the model we get information on all of the parameters and their priors. + +```python +print(model.info) +``` + +This gives the following output: + +```bash +galaxies + galaxy + redshift 0.5 + bulge + centre + centre_0 GaussianPrior, mean = 0.0, sigma = 0.3 + centre_1 GaussianPrior, mean = 0.0, sigma = 0.3 + ell_comps + ell_comps_0 GaussianPrior, mean = 0.0, sigma = 0.5 + ell_comps_1 GaussianPrior, mean = 0.0, sigma = 0.5 + intensity LogUniformPrior, lower_limit = 1e-06, upper_limit = 1000000.0 + effective_radius UniformPrior, lower_limit = 0.0, upper_limit = 30.0 + sersic_index UniformPrior, lower_limit = 0.8, upper_limit = 5.0 +``` + +## More Complex Models + +The API above can be easily extended to compose models where each galaxy has multiple light or mass profiles: + +```python +bulge = af.Model(ag.lp.Sersic) +disk = af.Model(ag.lp.Exponential) +bar = af.Model(ag.lp.Sersic) + +galaxy = af.Model( + ag.Galaxy, + redshift=0.5, + bulge=bulge, + disk=disk, + bar=bar +) + +model = af.Collection(galaxies=af.Collection(galaxy=galaxy)) +``` + +The use of the words `bulge`, `disk` and `bar` above are arbitrary. They can be replaced with any name you +like, e.g. `bulge_0`, `bulge_1`, `star_clump`, and the model will still behave in the same way. + +The API can also be extended to compose models where there are multiple galaxies: + +```python +bulge = af.Model(ag.lp.Sersic) + +galaxy_0 = af.Model( + ag.Galaxy, + redshift=0.5, + bulge=bulge, +) + +bulge = af.Model(ag.lp.Sersic) + +galaxy_1 = af.Model( + ag.Galaxy, + redshift=0.5, + bulge=bulge, +) + +model = af.Collection( + galaxies=af.Collection( + galaxy_0=galaxy_0, + galaxy_1=galaxy_1, + ) +) +``` + +## Concise API + +If a light profile is passed directly to the `af.Model` of a galaxy, it is automatically assigned to be a `af.Model` +component of the galaxy. + +This means we can write the model above comprising multiple light profiles more concisely as follows: + +```python +galaxy = af.Model( + ag.Galaxy, + redshift=0.5, + bulge=ag.lp.Sersic, + disk=ag.lp.Exponential, + bar=ag.lp.Sersic +) + +model = af.Collection(galaxies=af.Collection(galaxy=galaxy)) +``` + +## Prior Customization + +We can customize the priors of the model component individual parameters as follows: + +```python +bulge = af.Model(ag.lp.Sersic) +bulge.centre.centre_0 = af.UniformPrior(lower_limit=-0.1, upper_limit=0.1) +bulge.centre.centre_1 = af.UniformPrior(lower_limit=-0.1, upper_limit=0.1) +bulge.intensity = af.LogUniformPrior(lower_limit=1e-4, upper_limit=1e4) +bulge.sersic_index = af.GaussianPrior(mean=4.0, sigma=1.0, lower_limit=1.0, upper_limit=8.0) + +galaxy = af.Model( + ag.Galaxy, + redshift=0.5, + bulge=bulge, +) + +model = af.Collection(galaxies=af.Collection(galaxy=galaxy)) +``` + +## Model Customization + +We can customize the model parameters in a number of different ways, as shown below: + +```python +bulge = af.Model(ag.lp.Sersic) +disk = af.Model(ag.lp.Exponential) + +# Parameter Pairing: Pair the centre of the bulge and disk together, reducing +# the complexity of non-linear parameter space by N = 2 + +bulge.centre = disk.centre + +# Parameter Fixing: Fix the sersic_index of the bulge to a value of 4, reducing +# the complexity of non-linear parameter space by N = 1 + +bulge.sersic_index = 4.0 + +# Parameter Offsets: Make the bulge intensity parameters the same value as +# the disk but with an offset. + +bulge.intensity = disk.intensity + 0.1 + +galaxy = af.Model( + ag.Galaxy, + redshift=0.5, + bulge=bulge, + disk=disk, +) + +model = af.Collection(galaxies=af.Collection(galaxy=galaxy)) + +# Assert that the effective radius of the bulge is larger than that of the disk. +# (Assertions can only be added at the end of model composition, after all components +# have been bright together in a `Collection`. +model.add_assertion(model.galaxies.galaxy.bulge.effective_radius > model.galaxies.galaxy.disk.effective_radius) + +# Assert that the bulge effetive radius is below 3.0": +model.add_assertion(model.galaxies.galaxy.bulge.effective_radius < 3.0) +``` + +## Available Model Components + +The light profiles, mass profiles and other components that can be used for galaxy modeling are given at the following +API documentation pages: + +> - +> - +> - + +## JSon Outputs + +After a model is composed, it can easily be output to a .json file on hard-disk in a readable structure: + +```python +import os +import json + +model_path = path.join("path", "to", "model", "json") + +os.makedirs(model_path, exist_ok=True) + +model_file = path.join(model_path, "model.json") + +with open(model_file, "w+") as f: + json.dump(model.dict(), f, indent=4) +``` + +We can load the model from its `.json` file. + +```python +model = af.Model.from_json(file=model_file) +``` + +This means in **PyAutoGalaxy** one can write a model in a script, save it to hard disk and load it elsewhere, as well +as manually customize it in the .json file directory. + +## Many Profile Models (Advanced) + +Features such as the Multi Gaussian Expansion (MGE) and shapelets compose models consisting of 50 - 500+ light +profiles. + +The following example notebooks show how to compose and fit these models: + + + + +## Model Linking (Advanced) + +When performing non-linear search chaining, the inferred model of one phase can be linked to the model. + +The following example notebooks show how to compose and fit these models: + + + +## Across Datasets (Advanced) + +When fitting multiple datasets, model can be composed where the same model component are used across the datasets +but certain parameters are free to vary across the datasets. + +The following example notebooks show how to compose and fit these models: + + + +## Relations (Advanced) + +We can compose models where the free parameter(s) vary according to a user-specified function +(e.g. y = mx +c -> intensity = (m * wavelength) + c across the datasets. + +The following example notebooks show how to compose and fit these models: + + + +## PyAutoFit API + +**PyAutoFit** is a general model composition library which offers even more ways to compose models not +detailed in this cookbook. + +The **PyAutoFit** model composition cookbooks detail this API in more detail: + + + + +## Wrap Up + +This cookbook shows how to compose simple models using the `af.Model()` and `af.Collection()` objects. diff --git a/docs/general/model_cookbook.rst b/docs/general/model_cookbook.rst deleted file mode 100644 index 1dfaf8afd..000000000 --- a/docs/general/model_cookbook.rst +++ /dev/null @@ -1,283 +0,0 @@ -.. _model_cookbook: - -Model Cookbook -============== - -The model cookbook provides a concise reference to model composition tools, specifically the ``Model`` -and ``Collection`` objects. - -Examples using different **PyAutoGalaxy** API’s for model composition are provided, which produce more concise and -readable code for different use-cases. - -Simple Model ------------- - -A simple model we can compose has a galaxy with a Sersic light profile: - -.. code-block:: python - - bulge = af.Model(ag.lp.Sersic) - - galaxy = af.Model(ag.Galaxy, redshift=0.5, bulge=bulge) - - model = af.Collection(galaxies=af.Collection(galaxy=galaxy)) - -The model ``total_free_parameters`` tells us the total number of free parameters (which are fitted for via a -non-linear search), which in this case is 7. - -.. code-block:: python - - print(f"Model Total Free Parameters = {model.total_free_parameters}") - -If we print the ``info`` attribute of the model we get information on all of the parameters and their priors. - -.. code-block:: python - - print(model.info) - -This gives the following output: - -.. code-block:: bash - - galaxies - galaxy - redshift 0.5 - bulge - centre - centre_0 GaussianPrior, mean = 0.0, sigma = 0.3 - centre_1 GaussianPrior, mean = 0.0, sigma = 0.3 - ell_comps - ell_comps_0 GaussianPrior, mean = 0.0, sigma = 0.5 - ell_comps_1 GaussianPrior, mean = 0.0, sigma = 0.5 - intensity LogUniformPrior, lower_limit = 1e-06, upper_limit = 1000000.0 - effective_radius UniformPrior, lower_limit = 0.0, upper_limit = 30.0 - sersic_index UniformPrior, lower_limit = 0.8, upper_limit = 5.0 - -More Complex Models -------------------- - -The API above can be easily extended to compose models where each galaxy has multiple light or mass profiles: - -.. code-block:: python - - bulge = af.Model(ag.lp.Sersic) - disk = af.Model(ag.lp.Exponential) - bar = af.Model(ag.lp.Sersic) - - galaxy = af.Model( - ag.Galaxy, - redshift=0.5, - bulge=bulge, - disk=disk, - bar=bar - ) - - model = af.Collection(galaxies=af.Collection(galaxy=galaxy)) - -The use of the words `bulge`, `disk` and `bar` above are arbitrary. They can be replaced with any name you -like, e.g. `bulge_0`, `bulge_1`, `star_clump`, and the model will still behave in the same way. - -The API can also be extended to compose models where there are multiple galaxies: - -.. code-block:: python - - bulge = af.Model(ag.lp.Sersic) - - galaxy_0 = af.Model( - ag.Galaxy, - redshift=0.5, - bulge=bulge, - ) - - bulge = af.Model(ag.lp.Sersic) - - galaxy_1 = af.Model( - ag.Galaxy, - redshift=0.5, - bulge=bulge, - ) - - model = af.Collection( - galaxies=af.Collection( - galaxy_0=galaxy_0, - galaxy_1=galaxy_1, - ) - ) - - -Concise API ------------ - -If a light profile is passed directly to the `af.Model` of a galaxy, it is automatically assigned to be a `af.Model` -component of the galaxy. - -This means we can write the model above comprising multiple light profiles more concisely as follows: - -.. code-block:: python - - galaxy = af.Model( - ag.Galaxy, - redshift=0.5, - bulge=ag.lp.Sersic, - disk=ag.lp.Exponential, - bar=ag.lp.Sersic - ) - - model = af.Collection(galaxies=af.Collection(galaxy=galaxy)) - -Prior Customization -------------------- - -We can customize the priors of the model component individual parameters as follows: - -.. code-block:: python - - bulge = af.Model(ag.lp.Sersic) - bulge.centre.centre_0 = af.UniformPrior(lower_limit=-0.1, upper_limit=0.1) - bulge.centre.centre_1 = af.UniformPrior(lower_limit=-0.1, upper_limit=0.1) - bulge.intensity = af.LogUniformPrior(lower_limit=1e-4, upper_limit=1e4) - bulge.sersic_index = af.GaussianPrior(mean=4.0, sigma=1.0, lower_limit=1.0, upper_limit=8.0) - - galaxy = af.Model( - ag.Galaxy, - redshift=0.5, - bulge=bulge, - ) - - model = af.Collection(galaxies=af.Collection(galaxy=galaxy)) - -Model Customization -------------------- - -We can customize the model parameters in a number of different ways, as shown below: - -.. code-block:: python - - bulge = af.Model(ag.lp.Sersic) - disk = af.Model(ag.lp.Exponential) - - # Parameter Pairing: Pair the centre of the bulge and disk together, reducing - # the complexity of non-linear parameter space by N = 2 - - bulge.centre = disk.centre - - # Parameter Fixing: Fix the sersic_index of the bulge to a value of 4, reducing - # the complexity of non-linear parameter space by N = 1 - - bulge.sersic_index = 4.0 - - # Parameter Offsets: Make the bulge intensity parameters the same value as - # the disk but with an offset. - - bulge.intensity = disk.intensity + 0.1 - - galaxy = af.Model( - ag.Galaxy, - redshift=0.5, - bulge=bulge, - disk=disk, - ) - - model = af.Collection(galaxies=af.Collection(galaxy=galaxy)) - - # Assert that the effective radius of the bulge is larger than that of the disk. - # (Assertions can only be added at the end of model composition, after all components - # have been bright together in a `Collection`. - model.add_assertion(model.galaxies.galaxy.bulge.effective_radius > model.galaxies.galaxy.disk.effective_radius) - - # Assert that the bulge effetive radius is below 3.0": - model.add_assertion(model.galaxies.galaxy.bulge.effective_radius < 3.0) - -Available Model Components --------------------------- - -The light profiles, mass profiles and other components that can be used for galaxy modeling are given at the following -API documentation pages: - - - https://pyautogalaxy.readthedocs.io/en/latest/api/light.html - - https://pyautogalaxy.readthedocs.io/en/latest/api/mass.html - - https://pyautogalaxy.readthedocs.io/en/latest/api/pixelization.html - -JSon Outputs ------------- - -After a model is composed, it can easily be output to a .json file on hard-disk in a readable structure: - -.. code-block:: python - - import os - import json - - model_path = path.join("path", "to", "model", "json") - - os.makedirs(model_path, exist_ok=True) - - model_file = path.join(model_path, "model.json") - - with open(model_file, "w+") as f: - json.dump(model.dict(), f, indent=4) - -We can load the model from its ``.json`` file. - -.. code-block:: python - - model = af.Model.from_json(file=model_file) - -This means in **PyAutoGalaxy** one can write a model in a script, save it to hard disk and load it elsewhere, as well -as manually customize it in the .json file directory. - -Many Profile Models (Advanced) ------------------------------- - -Features such as the Multi Gaussian Expansion (MGE) and shapelets compose models consisting of 50 - 500+ light -profiles. - -The following example notebooks show how to compose and fit these models: - -https://github.com/Jammy2211/autogalaxy_workspace/blob/release/notebooks/modeling/imaging/features/multi_gaussian_expansion.ipynb -https://github.com/Jammy2211/autogalaxy_workspace/blob/release/notebooks/modeling/imaging/features/shapelets.ipynb - -Model Linking (Advanced) ------------------------- - -When performing non-linear search chaining, the inferred model of one phase can be linked to the model. - -The following example notebooks show how to compose and fit these models: - -https://github.com/Jammy2211/autogalaxy_workspace/blob/release/notebooks/imaging/advanced/chaining/start_here.ipynb - -Across Datasets (Advanced) --------------------------- - -When fitting multiple datasets, model can be composed where the same model component are used across the datasets -but certain parameters are free to vary across the datasets. - -The following example notebooks show how to compose and fit these models: - -https://github.com/Jammy2211/autogalaxy_workspace/blob/release/notebooks/multi/modeling/start_here.ipynb - -Relations (Advanced) --------------------- - -We can compose models where the free parameter(s) vary according to a user-specified function -(e.g. y = mx +c -> intensity = (m * wavelength) + c across the datasets. - -The following example notebooks show how to compose and fit these models: - -https://github.com/Jammy2211/autogalaxy_workspace/blob/release/notebooks/multi/modeling/features/wavelength_dependence.ipynb - -PyAutoFit API -------------- - -**PyAutoFit** is a general model composition library which offers even more ways to compose models not -detailed in this cookbook. - -The **PyAutoFit** model composition cookbooks detail this API in more detail: - -https://pyautofit.readthedocs.io/en/latest/cookbooks/model.html -https://pyautofit.readthedocs.io/en/latest/cookbooks/multi_level_model.html - -Wrap Up -------- - -This cookbook shows how to compose simple models using the ``af.Model()`` and ``af.Collection()`` objects. diff --git a/docs/general/papers.md b/docs/general/papers.md new file mode 100644 index 000000000..0ebb3536a --- /dev/null +++ b/docs/general/papers.md @@ -0,0 +1,9 @@ +(papers)= + +# Papers + +The following papers use **PyAutoGalaxy**: + +**Statistics / Machine Learning** + +[Streamlined Lensed Quasar Identification in Multiband Images via Ensemble Networks](https://arxiv.org/abs/2307.01090) diff --git a/docs/general/papers.rst b/docs/general/papers.rst deleted file mode 100644 index bb8faee97..000000000 --- a/docs/general/papers.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _papers: - -Papers ------- - -The following papers use **PyAutoGalaxy**: - -**Statistics / Machine Learning** - -`Streamlined Lensed Quasar Identification in Multiband Images via Ensemble Networks `_ \ No newline at end of file diff --git a/docs/general/workspace.md b/docs/general/workspace.md new file mode 100644 index 000000000..9b2953b38 --- /dev/null +++ b/docs/general/workspace.md @@ -0,0 +1,53 @@ +(workspace)= + +# Workspace Tour + +You should have downloaded and configured the [autogalaxy workspace](https://github.com/Jammy2211/autogalaxy_workspace) +when you installed **PyAutoGalaxy**. If you didn't, checkout the +[installation instructions](https://pyautogalaxy.readthedocs.io/en/latest/general/installation.html#installation-with-pip) +for how to downloaded and configure the workspace. + +The `README.rst` files distributed throughout the workspace describe every folder and file, and specify if +examples are for beginner or advanced users. + +New users should begin by checking out the following parts of the workspace. + +## Scripts / Notebooks + +There are numerous example describing how to perform calculations, galaxy modeling, and many other +**PyAutoGalaxy** features. All examples are provided as Python scripts and Jupyter notebooks. + +A full description of the scripts available is given on +the [autogalaxy workspace GitHub page](https://github.com/Jammy2211/autogalaxy_workspace). + +## Config + +Here, you'll find the configuration files which customize: + +> - The default settings used by every non-linear search. +> - Visualization, including the backend used by *matplotlib*. +> - The priors and notation configs associated with the light and mass profiles used for lens modeling. +> - The behaviour of different (y,x) Cartesian grids used to perform lens calculations. +> - The generaltrue config which customizes other aspects of **PyAutoGalaxy**. + +Descriptions of every configuration file and their input parameters are provided in the `README.rst` in +the [config directory of the workspace](https://github.com/Jammy2211/autogalaxy_workspace/tree/release/config) + +## Dataset + +Contains the dataset's used to perform lens modeling. Example datasets using simulators included with the workspace +are included here by default. + +## Output + +The folder where modeling results are stored. + +## HowToGalaxy + +The **HowToGalaxy** lecture series is a collection of Jupyter notebooks describing how to build a **PyAutoGalaxy** model +fitting project and giving illustrations of different statistical methods and techniques. It ships as a standalone +repository at [PyAutoLabs/HowToGalaxy](https://github.com/PyAutoLabs/HowToGalaxy) (separate from the workspace). + +Checkout the +[tutorials section](https://pyautogalaxy.readthedocs.io/en/latest/howtogalaxy/howtogalaxy.html) for a +full description of the lectures and online examples of every notebook. diff --git a/docs/general/workspace.rst b/docs/general/workspace.rst deleted file mode 100644 index 4f5808ec5..000000000 --- a/docs/general/workspace.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _workspace: - -Workspace Tour -============== - -You should have downloaded and configured the `autogalaxy workspace `_ -when you installed **PyAutoGalaxy**. If you didn't, checkout the -`installation instructions `_ -for how to downloaded and configure the workspace. - -The ``README.rst`` files distributed throughout the workspace describe every folder and file, and specify if -examples are for beginner or advanced users. - -New users should begin by checking out the following parts of the workspace. - -Scripts / Notebooks -------------------- - -There are numerous example describing how to perform calculations, galaxy modeling, and many other -**PyAutoGalaxy** features. All examples are provided as Python scripts and Jupyter notebooks. - -A full description of the scripts available is given on -the `autogalaxy workspace GitHub page `_. - -Config ------- - -Here, you'll find the configuration files which customize: - - - The default settings used by every non-linear search. - - Visualization, including the backend used by *matplotlib*. - - The priors and notation configs associated with the light and mass profiles used for lens modeling. - - The behaviour of different (y,x) Cartesian grids used to perform lens calculations. - - The generaltrue config which customizes other aspects of **PyAutoGalaxy**. - -Descriptions of every configuration file and their input parameters are provided in the ``README.rst`` in -the `config directory of the workspace `_ - -Dataset -------- - -Contains the dataset's used to perform lens modeling. Example datasets using simulators included with the workspace -are included here by default. - -Output ------- - -The folder where modeling results are stored. - -HowToGalaxy ------------ - -The **HowToGalaxy** lecture series is a collection of Jupyter notebooks describing how to build a **PyAutoGalaxy** model -fitting project and giving illustrations of different statistical methods and techniques. It ships as a standalone -repository at `PyAutoLabs/HowToGalaxy `_ (separate from the workspace). - -Checkout the -`tutorials section `_ for a -full description of the lectures and online examples of every notebook. \ No newline at end of file diff --git a/docs/howtogalaxy/chapter_1_introduction.md b/docs/howtogalaxy/chapter_1_introduction.md new file mode 100644 index 000000000..3475549c1 --- /dev/null +++ b/docs/howtogalaxy/chapter_1_introduction.md @@ -0,0 +1,25 @@ +# Chapter 1: Galaxies + +In chapter 1, we introduce you to galaxy morphology, structure and the core **PyAutoGalaxy** API. + +**Colab** links to every tutorial are included. + +The chapter contains the following tutorials: + +[Tutorial 0: Visualization](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_0_visualization.ipynb) +\- Setting up **PyAutoGalaxy**'s visualization library. + +[Tutorial 1: Grids And Galaxies](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_1_grids_and_galaxies.ipynb) +\- Using grids of (y,x) coordinates with galaxies made up of light profiles. + +[Tutorial 2: Data](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_2_data.ipynb) +\- Simulating and inspecting telescope imaging data of a galaxy. + +[Tutorial 3: Fitting](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_3_fitting.ipynb) +\- Fitting data with a galaxy model. + +[Tutorial 4: Methods](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_4_methods.ipynb) +\- An overview of the different methods used to fit galaxies with. + +[Tutorial 5: Summary](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_5_summary.ipynb) +\- A summary of the chapter. diff --git a/docs/howtogalaxy/chapter_1_introduction.rst b/docs/howtogalaxy/chapter_1_introduction.rst deleted file mode 100644 index 656d8e5a7..000000000 --- a/docs/howtogalaxy/chapter_1_introduction.rst +++ /dev/null @@ -1,26 +0,0 @@ -Chapter 1: Galaxies -=================== - -In chapter 1, we introduce you to galaxy morphology, structure and the core **PyAutoGalaxy** API. - -**Colab** links to every tutorial are included. - -The chapter contains the following tutorials: - -`Tutorial 0: Visualization `_ -- Setting up **PyAutoGalaxy**'s visualization library. - -`Tutorial 1: Grids And Galaxies `_ -- Using grids of (y,x) coordinates with galaxies made up of light profiles. - -`Tutorial 2: Data `_ -- Simulating and inspecting telescope imaging data of a galaxy. - -`Tutorial 3: Fitting `_ -- Fitting data with a galaxy model. - -`Tutorial 4: Methods `_ -- An overview of the different methods used to fit galaxies with. - -`Tutorial 5: Summary `_ -- A summary of the chapter. \ No newline at end of file diff --git a/docs/howtogalaxy/chapter_2_modeling.md b/docs/howtogalaxy/chapter_2_modeling.md new file mode 100644 index 000000000..613d5493f --- /dev/null +++ b/docs/howtogalaxy/chapter_2_modeling.md @@ -0,0 +1,29 @@ +# Chapter 2: Modeling + +In chapter 2, we'll take you through how to model galaxies using a non-linear search. + +The chapter contains the following tutorials: + +[Tutorial 1: Non-linear Search](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_2_modeling/tutorial_1_non_linear_search.ipynb) +\- How a non-linear search is used to fit a model and the concepts of a parameter space and priors. + +[Tutorial 2: Practicalities](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_2_modeling/tutorial_2_practicalities.ipynb) +\- Practicalities of performing model-fitting, like how to inspect the results on your hard-disk. + +[Tutorial 3: Realism and Complexity](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_2_modeling/tutorial_3_realism_and_complexity.ipynb) +\- Finding a balance between realism and complexity when composing and fitting a model. + +[Tutorial 4: Dealing with Failure](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_2_modeling/tutorial_4_dealing_with_failure.ipynb) +\- What to do when PyAutoGalaxy finds an inaccurate model. + +[Tutorial 5: Linear Profiles](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_2_modeling/tutorial_5_linear_profiles.ipynb) +\- Light profiles which capture complex morphologies in a reduced number of non-linear parameters. + +[Tutorial 6: Masking](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_2_modeling/tutorial_6_masking.ipynb) +\- How to mask your data to improve the model. + +[Tutorial 7: Results](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_2_modeling/tutorial_7_results.ipynb) +\- Overview of the results available after successfully fitting a model. + +[Tutorial 8: Need for Speed](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_2_modeling/tutorial_8_need_for_speed.ipynb) +\- How to fit complex models whilst balancing efficiency and run-time. diff --git a/docs/howtogalaxy/chapter_2_modeling.rst b/docs/howtogalaxy/chapter_2_modeling.rst deleted file mode 100644 index 83a1023a4..000000000 --- a/docs/howtogalaxy/chapter_2_modeling.rst +++ /dev/null @@ -1,31 +0,0 @@ -Chapter 2: Modeling -=================== - -In chapter 2, we'll take you through how to model galaxies using a non-linear search. - -The chapter contains the following tutorials: - -`Tutorial 1: Non-linear Search `_ -- How a non-linear search is used to fit a model and the concepts of a parameter space and priors. - -`Tutorial 2: Practicalities `_ -- Practicalities of performing model-fitting, like how to inspect the results on your hard-disk. - -`Tutorial 3: Realism and Complexity `_ -- Finding a balance between realism and complexity when composing and fitting a model. - -`Tutorial 4: Dealing with Failure `_ -- What to do when PyAutoGalaxy finds an inaccurate model. - -`Tutorial 5: Linear Profiles `_ -- Light profiles which capture complex morphologies in a reduced number of non-linear parameters. - -`Tutorial 6: Masking `_ -- How to mask your data to improve the model. - -`Tutorial 7: Results `_ -- Overview of the results available after successfully fitting a model. - -`Tutorial 8: Need for Speed `_ -- How to fit complex models whilst balancing efficiency and run-time. - diff --git a/docs/howtogalaxy/chapter_3_search_chaining.md b/docs/howtogalaxy/chapter_3_search_chaining.md new file mode 100644 index 000000000..520d29b78 --- /dev/null +++ b/docs/howtogalaxy/chapter_3_search_chaining.md @@ -0,0 +1,15 @@ +# Chapter 3: Search Chaining + +In chapter 3, we introduce non-linear search chaining, whereby model-fits are chained together to enable efficient and +robust modeling of large galaxy samples. + +The chapter contains the following tutorials: + +[Tutorial 1: Search Chaining](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_3_search_chaining/tutorial_1_search_chaining.ipynb) +\- Breaking the modeling procedure into a chained sequence of model-fits. + +[Tutorial 2: Prior Passing](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_3_search_chaining/tutorial_2_prior_passing.ipynb) +\- How the results of earlier searches are passed to later searches. + +[Tutorial 3: x2 Galaxies](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_3_search_chaining/tutorial_3_x2_galaxies.ipynb) +\- Modeling a dataset with two galaxies using chained searches. diff --git a/docs/howtogalaxy/chapter_3_search_chaining.rst b/docs/howtogalaxy/chapter_3_search_chaining.rst deleted file mode 100644 index 5818263ff..000000000 --- a/docs/howtogalaxy/chapter_3_search_chaining.rst +++ /dev/null @@ -1,16 +0,0 @@ -Chapter 3: Search Chaining -========================== - -In chapter 3, we introduce non-linear search chaining, whereby model-fits are chained together to enable efficient and -robust modeling of large galaxy samples. - -The chapter contains the following tutorials: - -`Tutorial 1: Search Chaining `_ -- Breaking the modeling procedure into a chained sequence of model-fits. - -`Tutorial 2: Prior Passing `_ -- How the results of earlier searches are passed to later searches. - -`Tutorial 3: x2 Galaxies `_ -- Modeling a dataset with two galaxies using chained searches. \ No newline at end of file diff --git a/docs/howtogalaxy/chapter_4_pixelizations.md b/docs/howtogalaxy/chapter_4_pixelizations.md new file mode 100644 index 000000000..9a5143771 --- /dev/null +++ b/docs/howtogalaxy/chapter_4_pixelizations.md @@ -0,0 +1,20 @@ +# Chapter 4: Pixelizations + +In chapter 4, we use **Pixelizations** to reconstruct complex galaxies on pixelized grids. + +The chapter contains the following tutorials: + +[Tutorial 1: Pixelizations](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_4_pixelizations/tutorial_1_pixelizations.ipynb) +\- Creating a pixel-grid which will reconstruct a galaxy's light. + +[Tutorial 2: Mappers](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_4_pixelizations/tutorial_2_mappers.ipynb) +\- How a pixelization maps between the data and pixelization. + +[Tutorial 3: Inversions](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_4_pixelizations/tutorial_3_inversions.ipynb) +\- Inverting the mappings to reconstruct the galaxy's light. + +[Tutorial 4: Bayesian Regularization](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_4_pixelizations/tutorial_4_bayesian_regularization.ipynb) +\- Smoothing the source within a Bayesian framework. + +[Tutorial 6: Model Fit](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_4_pixelizations/tutorial_6_model_fit.ipynb) +\- An example modeling pipeline which uses an inversion. diff --git a/docs/howtogalaxy/chapter_4_pixelizations.rst b/docs/howtogalaxy/chapter_4_pixelizations.rst deleted file mode 100644 index b5b70db22..000000000 --- a/docs/howtogalaxy/chapter_4_pixelizations.rst +++ /dev/null @@ -1,21 +0,0 @@ -Chapter 4: Pixelizations -======================== - -In chapter 4, we use **Pixelizations** to reconstruct complex galaxies on pixelized grids. - -The chapter contains the following tutorials: - -`Tutorial 1: Pixelizations `_ -- Creating a pixel-grid which will reconstruct a galaxy's light. - -`Tutorial 2: Mappers `_ -- How a pixelization maps between the data and pixelization. - -`Tutorial 3: Inversions `_ -- Inverting the mappings to reconstruct the galaxy's light. - -`Tutorial 4: Bayesian Regularization `_ -- Smoothing the source within a Bayesian framework. - -`Tutorial 6: Model Fit `_ -- An example modeling pipeline which uses an inversion. \ No newline at end of file diff --git a/docs/howtogalaxy/chapter_optional.md b/docs/howtogalaxy/chapter_optional.md new file mode 100644 index 000000000..1172f33f4 --- /dev/null +++ b/docs/howtogalaxy/chapter_optional.md @@ -0,0 +1,14 @@ +# Chapter: Optional + +This chapter contains optional tutorials expanding on different aspects of how **PyAutoGalaxy** work. + +The chapter contains the following tutorials: + +[Tutorial: Mass Profiles](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_optional/tutorial_mass_profiles.ipynb) +\- A description of mass profiles implemented in PyAutoGalaxy, which are currently only used by its child project PyAutoLens. + +[Tutorial: Sub-grids](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_optional/tutorial_sub_grids.ipynb) +\- Use sub-grids to perform more accurate and precise calculations. + +[Tutorial: Searches](https://colab.research.google.com/github/PyAutoLabs/HowToGalaxy/blob/2026.5.1.4/notebooks/chapter_optional/tutorial_searches.ipynb) +\- Alternative non-linear searches to sample parameter space. diff --git a/docs/howtogalaxy/chapter_optional.rst b/docs/howtogalaxy/chapter_optional.rst deleted file mode 100644 index a94d25f72..000000000 --- a/docs/howtogalaxy/chapter_optional.rst +++ /dev/null @@ -1,16 +0,0 @@ -Chapter: Optional -================= - -This chapter contains optional tutorials expanding on different aspects of how **PyAutoGalaxy** work. - -The chapter contains the following tutorials: - -`Tutorial: Mass Profiles `_ -- A description of mass profiles implemented in PyAutoGalaxy, which are currently only used by its child project PyAutoLens. - -`Tutorial: Sub-grids `_ -- Use sub-grids to perform more accurate and precise calculations. - -`Tutorial: Searches `_ -- Alternative non-linear searches to sample parameter space. - diff --git a/docs/howtogalaxy/howtogalaxy.rst b/docs/howtogalaxy/howtogalaxy.md similarity index 80% rename from docs/howtogalaxy/howtogalaxy.rst rename to docs/howtogalaxy/howtogalaxy.md index 22300d5cf..2bbdb1e24 100644 --- a/docs/howtogalaxy/howtogalaxy.rst +++ b/docs/howtogalaxy/howtogalaxy.md @@ -1,65 +1,60 @@ -.. _howtogalaxy: - -HowToGalaxy Lectures -==================== - -The best way to learn **PyAutoGalaxy** is by going through the **HowToGalaxy** lecture series, which lives in its own -repository at `PyAutoLabs/HowToGalaxy `_. - -The lectures are provided as Jupyter notebooks (and Python scripts), and they are linked to via this readthedocs. The -lectures are composed of five chapters - -- **Introduction** - An introduction to galaxy morphology and structure using **PyAutoGalaxy**. -- **Lens Modeling** - How to model galaxies, including a primer on Bayesian non-linear analysis. -- **Search Chaining** - How to fit complex lens models using non-linear search chaining. -- **Pixelizations** - How to perform pixelized reconstructions of a galaxy. - -How to Tackle HowToGalaxy -------------------------- - -The **HowToGalaxy** lecture series current sits at 4 chapters, and each will take a day or so to go through -properly. You probably want to be modeling galaxies faster than that! Furthermore, the concepts -in the later chapters are pretty challenging, and familiarity and modeling is desirable before -you tackle them. - -Therefore, we recommend that you complete chapters 1 & 2 and then apply what you've learnt to the modeling of simulated -and real galaxy data, using the scripts found in the -`autogalaxy_workspace `_. Once you're happy -with the results and confident with your use of **PyAutoGalaxy**, you can then begin to cover the advanced functionality -covered in chapters 3 & 4. - -Jupyter Notebooks ------------------ - -The tutorials are supplied as Jupyter Notebooks, which come with a '.ipynb' suffix. For those new to Python, Jupyter -Notebooks are a different way to write, view and use Python code. Compared to the traditional Python scripts, they allow: - -- Small blocks of code to be viewed and run at a time -- Images and visualization from a code to be displayed directly underneath it. -- Text script to appear between the blocks of code. - -This makes them an ideal way for us to present the HowToFit lecture series, therefore I recommend you get yourself -a Jupyter notebook viewer (https://jupyter.org/) if you havent done so already. - -If you *really* want to use Python scripts, all tutorials are also supplied as ``.py`` files in the ``scripts`` folder -of the `HowToGalaxy repository `_. - -Visualization -------------- - -Before beginning the **HowToGalaxy** lecture series, in chapter 1 you should do 'tutorial_0_visualization'. This will -take you through how **PyAutoGalaxy** interfaces with matplotlib to perform visualization and will get you setup such -that images and figures display correctly in your Jupyter notebooks. - -Code Style and Formatting -------------------------- - -You may notice the style and formatting of our Python code looks different to what you are used to. For example, it -is common for brackets to be placed on their own line at the end of function calls, the inputs of a function or -class may be listed over many separate lines and the code in general takes up a lot more space then you are used to. - -This is intentional, because we believe it makes the cleanest, most readable code possible. In fact, lots of people do, -which is why we use an auto-formatter to produce the code in a standardized format. If you're interested in the style -and would like to adapt it to your own code, check out the Python auto-code formatter 'black'. - -https://github.com/python/black +(howtogalaxy)= + +# HowToGalaxy Lectures + +The best way to learn **PyAutoGalaxy** is by going through the **HowToGalaxy** lecture series, which lives in its own +repository at [PyAutoLabs/HowToGalaxy](https://github.com/PyAutoLabs/HowToGalaxy). + +The lectures are provided as Jupyter notebooks (and Python scripts), and they are linked to via this readthedocs. The +lectures are composed of five chapters + +- **Introduction** - An introduction to galaxy morphology and structure using **PyAutoGalaxy**. +- **Lens Modeling** - How to model galaxies, including a primer on Bayesian non-linear analysis. +- **Search Chaining** - How to fit complex lens models using non-linear search chaining. +- **Pixelizations** - How to perform pixelized reconstructions of a galaxy. + +## How to Tackle HowToGalaxy + +The **HowToGalaxy** lecture series current sits at 4 chapters, and each will take a day or so to go through +properly. You probably want to be modeling galaxies faster than that! Furthermore, the concepts +in the later chapters are pretty challenging, and familiarity and modeling is desirable before +you tackle them. + +Therefore, we recommend that you complete chapters 1 & 2 and then apply what you've learnt to the modeling of simulated +and real galaxy data, using the scripts found in the +[autogalaxy_workspace](https://github.com/PyAutoLabs/autogalaxy_workspace). Once you're happy +with the results and confident with your use of **PyAutoGalaxy**, you can then begin to cover the advanced functionality +covered in chapters 3 & 4. + +## Jupyter Notebooks + +The tutorials are supplied as Jupyter Notebooks, which come with a '.ipynb' suffix. For those new to Python, Jupyter +Notebooks are a different way to write, view and use Python code. Compared to the traditional Python scripts, they allow: + +- Small blocks of code to be viewed and run at a time +- Images and visualization from a code to be displayed directly underneath it. +- Text script to appear between the blocks of code. + +This makes them an ideal way for us to present the HowToFit lecture series, therefore I recommend you get yourself +a Jupyter notebook viewer () if you havent done so already. + +If you *really* want to use Python scripts, all tutorials are also supplied as `.py` files in the `scripts` folder +of the [HowToGalaxy repository](https://github.com/PyAutoLabs/HowToGalaxy). + +## Visualization + +Before beginning the **HowToGalaxy** lecture series, in chapter 1 you should do 'tutorial_0_visualization'. This will +take you through how **PyAutoGalaxy** interfaces with matplotlib to perform visualization and will get you setup such +that images and figures display correctly in your Jupyter notebooks. + +## Code Style and Formatting + +You may notice the style and formatting of our Python code looks different to what you are used to. For example, it +is common for brackets to be placed on their own line at the end of function calls, the inputs of a function or +class may be listed over many separate lines and the code in general takes up a lot more space then you are used to. + +This is intentional, because we believe it makes the cleanest, most readable code possible. In fact, lots of people do, +which is why we use an auto-formatter to produce the code in a standardized format. If you're interested in the style +and would like to adapt it to your own code, check out the Python auto-code formatter 'black'. + + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..e4e8cc412 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,264 @@ +--- +substitutions: + pic1: |- + ```{image} https://github.com/Jammy2211/PyAutoGalaxy/blob/main/paper/hstcombined.png?raw=true + ``` + pic2: |- + ```{image} https://github.com/Jammy2211/PyAutoGalaxy/blob/main/paper/almacombined.png?raw=true + ``` +--- + +# What is PyAutoGalaxy? + +**PyAutoGalaxy** is software for analysing the morphologies and structures of galaxies: + +{{ pic1 }} + +**PyAutoGalaxy** also fits interferometer data from observatories such as ALMA: + +{{ pic2 }} + +# Getting Started + +The following links are useful for new starters: + +- [The PyAutoGalaxy readthedocs](https://pyautogalaxy.readthedocs.io/en/latest/), which includes [an overview of PyAutoGalaxy's core features](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_1_start_here.html), [a new user starting guide](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_2_new_user_guide.html) and [an installation guide](https://pyautogalaxy.readthedocs.io/en/latest/installation/overview.html). +- [The introduction Jupyter Notebook on Colab](https://colab.research.google.com/github/PyAutoLabs/autogalaxy_workspace/blob/2026.5.1.4/start_here.ipynb), where you can try **PyAutoGalaxy** in a web browser (without installation). +- [The autogalaxy_workspace GitHub repository](https://github.com/PyAutoLabs/autogalaxy_workspace): example scripts covering every **PyAutoGalaxy** use case. +- [The HowToGalaxy GitHub repository](https://github.com/PyAutoLabs/HowToGalaxy): a Jupyter notebook lecture series teaching galaxy modeling from the ground up. + +# Core Aims + +**PyAutoGalaxy** has three core aims: + +- **Big Data**: Scaling automated Sérsic fitting to extremely large datasets, *accelerated with JAX on GPUs and using tools like an SQL database to \*\*build a scalable scientific workflow\*\**. +- **Model Complexity**: Fitting complex galaxy morphology models (e.g. Multi Gaussian Expansion, Shapelets, Ellipse Fitting, Irregular Meshes) that go beyond just simple Sérsic fitting. +- **Data Variety**: Support for many data types (e.g. CCD imaging, interferometry, multi-band imaging) which can be fitted independently or simultaneously. + +# Features + +Core features include fully automated Bayesian model-fitting of galaxy two-dimensional surface brightness profiles, +support for dataset and interferometer datasets and comprehensive tools for simulating galaxy images. The software +places a focus on **big data** analysis, including support for hierarchical models that simultaneously fit thousands of +galaxies, massively parallel model-fitting and an SQLite3 database that allows large suites of modeling results to be +loaded, queried and analysed. + +The **HowToGalaxy** Jupyter notebook lectures, which live in their own +[PyAutoLabs/HowToGalaxy](https://github.com/PyAutoLabs/HowToGalaxy) repository, are written assuming no +previous knowledge about galaxy structure and teach a new user the theory and statistics required to analyse +galaxy data. Checkout [the howtogalaxy section of +the readthedocs](https://pyautogalaxy.readthedocs.io/en/latest/howtogalaxy/howtogalaxy.html). + +An overview of **PyAutoGalaxy**'s core features can be found in +the [overview section of the readthedocs](https://pyautogalaxy.readthedocs.io/en/latest/overview/lensing.html). + +# Galaxy Morphology & Structure + +The study of galaxy morphology aims to understand the different luminous structures that galaxies are composed of. +Using large CCD imaging datasets of galaxies observed at ultraviolet, optical and near-infrared wavelengths from +instruments like the Hubble Space Telescope (HST), Astronomers have uncovered the plentiful structures that make up +a galaxy (e.g. bars, bulges, disks and rings) and revealed that evolving galaxies transition from disk-like structures +to bulge-like elliptical galaxies. At sub-mm and radio wavelengths interferometer datasets from instruments like the +Atacama LAM (ALMA) have revealed the integral role that dust plays in forming a galaxy in the distant Universe, early +in its lifetime. Studies typically represent a galaxy's light using analytic functions such as the Sersic +profile, which quantify the global appearance of most galaxies into one of three groups: (i) bulge-like +structures which follow a dev Vaucouleurs profile; (ii) disk-like structures which follow an Exponential profile +or; (iii) irregular morphologies which are difficult to quantify with symmetric and smooth analytic profiles. Galaxies +are often composed of many sub-components which may be a combination of these different structures. + +In the next decade, wide field surveys such as Euclid, the Vera Rubin Observatory and Square Kilometer array are +poised to observe images of \_billions\_ of galaxies. Analysing these extremely large galaxy datasets demands +advanced Bayesian model-fitting techniques which can scale-up in a fully automated manner. Equally, the James Webb +Space Telescope, thirty-meter class ground telescopes and ?radio? will observe galaxies at an +unprecedented resolution and level of detail. This demands more flexible modeling techniques that can accurately +represent the complex irregular structures one such high resolution observations reveal. `PyAutoGalaxy` aims to meet +both these needs, by interfacing galaxy model-fitting with the probabilistic programming language `PyAutoFit` to +provide Bayesian fitting tools suited to big data analysis alongside image processing tools that represent irregular +galaxy structures using non-parametric models. + +# How does PyAutoGalaxy Work? + +At the heart of the `PyAutoGalaxy` API is the `Galaxy` object, which groups together one or more `LightProfile` objects +at an input redshift. Passing these objects a `Grid2D` returns an image of the galaxy(s), which can subsequently +be passed through `Operator` objects to apply a 2D convolution or Fast Fourier Transform and thereby compare +the `Galaxy`'s image to an imaging or interferometer dataset. The `inversion` package contains a range of non-parametric +models which fit a galaxy's light using a Bayesian linear matrix inversion. The `astropy` cosmology module is +used to handle unit conversions and calculations are optimized using the packages `NumPy` [@numpy], `numba` [@numba] +and `PyNUFFT` [@pynufft]. + +```python +import autogalaxy as ag +import autogalaxy.plot as aplt + +""" +To describe the galaxy emission two-dimensional grids of (y,x) Cartesian +coordinates are used. +""" +grid = ag.Grid2D.uniform( + shape_native=(50, 50), + pixel_scales=0.05, # <- Conversion from pixel units to arc-seconds. +) + +""" +The galaxy has an elliptical sersic light profile representing its bulge. +""" +bulge = ag.lp.Sersic( + centre=(0.0, 0.0), + ell_comps=ag.convert.ell_comps_from(axis_ratio=0.9, angle=45.0), + intensity=1.0, + effective_radius=0.6, + sersic_index=3.0, +) + +""" +The galaxy also has an elliptical exponential disk +""" +disk = ag.lp.Exponential( + centre=(0.0, 0.0), + ell_comps=ag.convert.ell_comps_from(axis_ratio=0.7, angle=30.0), + intensity=0.5, + effective_radius=1.6, +) + +""" +We combine the above light profiles to compose a galaxy at redshift 1.0. +""" +galaxy = ag.Galaxy(redshift=1.0, bulge=bulge, disk=disk) + +""" +We can use the grid and galaxies to perform many calculations, for example +plotting the image of the galaxies. +""" +galaxies_plotter = aplt.Galaxies(galaxies=[galaxy], grid=grid) +galaxies_plotter.figures_2d(image=True) +``` + +To perform model-fitting, `PyAutoGalaxy` adopts the probabilistic programming +language `PyAutoFit` (). `PyAutoFit` allows users to compose a +model from `LightProfile` and `Galaxy` objects, customize the model parameterization and fit it to data via a +non-linear search (e.g., `dynesty` [@dynesty], `emcee` [@emcee], `PySwarms` [@pyswarms]). By composing a model with +`Pixelization` objects, the galaxy's light is reconstructed using a non-parametric rectangular +grid or Voronoi mesh that accounts for irregular galaxy morphologies. + +```python +import autofit as af +import autogalaxy as ag + +import os + +""" +Load Imaging data of the galaxy from the dataset folder of the workspace. +""" +dataset = ag.Imaging.from_fits( + data_path="/path/to/dataset/image.fits", + noise_map_path="/path/to/dataset/noise_map.fits", + psf_path="/path/to/dataset/psf.fits", + pixel_scales=0.1, +) + +""" +Create a mask for the data, which we setup as a 3.0" circle. +""" +mask = ag.Mask2D.circular( + shape_native=dataset.shape_native, pixel_scales=dataset.pixel_scales, radius=3.0 +) + +""" +We model the galaxy using an Sersic LightProfile. +""" +light_profile = ag.lp.Sersic + +""" +We next setup this profile as model components whose parameters are free & fitted for +by setting up a Galaxy as a Model. +""" +galaxy_model = af.Model(ag.Galaxy, redshift=1.0, light=light_profile) +model = af.Collection(galaxy=galaxy_model) + +""" +We define the non-linear search used to fit the model to the data (in this case, Dynesty). +""" +search = af.Nautilus(name="search[example]", n_live=50) + +""" +We next set up the `Analysis`, which contains the `log likelihood function` that the +non-linear search calls to fit the lens model to the data. +""" +analysis = ag.AnalysisImaging(dataset=masked_dataset) + +""" +To perform the model-fit we pass the model and analysis to the search's fit method. This will +output results (e.g., dynesty samples, model parameters, visualization) to hard-disk. +""" +result = search.fit(model=model, analysis=analysis) + +""" +The results contain information on the fit, for example the maximum likelihood +model from the Dynesty parameter space search. +""" +print(result.samples.max_log_likelihood()) +``` + +```{toctree} +:caption: 'Overview:' +:hidden: true +:maxdepth: 1 + +overview/overview_1_start_here +overview/overview_2_new_user_guide +overview/overview_3_features +``` + +```{toctree} +:caption: 'Installation:' +:hidden: true +:maxdepth: 1 + +installation/overview +installation/conda +installation/pip +installation/numba +installation/source +installation/troubleshooting +``` + +```{toctree} +:caption: 'General:' +:hidden: true +:maxdepth: 1 + +general/workspace +general/configs +general/model_cookbook +general/likelihood_function +general/citations +general/credits +``` + +```{toctree} +:caption: 'Tutorials:' +:hidden: true +:maxdepth: 1 + +howtogalaxy/howtogalaxy +howtogalaxy/chapter_1_introduction +howtogalaxy/chapter_2_modeling +howtogalaxy/chapter_3_search_chaining +howtogalaxy/chapter_4_pixelizations +howtogalaxy/chapter_optional +``` + +```{toctree} +:caption: 'API Reference:' +:hidden: true +:maxdepth: 1 + +api/data +api/light +api/galaxy +api/fitting +api/modeling +api/pixelization +api/plot +api/source +``` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 01bcdc1fa..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,266 +0,0 @@ -What is PyAutoGalaxy? -===================== - -**PyAutoGalaxy** is software for analysing the morphologies and structures of galaxies: - -|pic1| - -.. |pic1| image:: https://github.com/Jammy2211/PyAutoGalaxy/blob/main/paper/hstcombined.png?raw=true - -**PyAutoGalaxy** also fits interferometer data from observatories such as ALMA: - -|pic2| - -.. |pic2| image:: https://github.com/Jammy2211/PyAutoGalaxy/blob/main/paper/almacombined.png?raw=true - - -Getting Started -=============== - -The following links are useful for new starters: - -- `The PyAutoGalaxy readthedocs `_, which includes `an overview of PyAutoGalaxy's core features `_, `a new user starting guide `_ and `an installation guide `_. - -- `The introduction Jupyter Notebook on Colab `_, where you can try **PyAutoGalaxy** in a web browser (without installation). - -- `The autogalaxy_workspace GitHub repository `_: example scripts covering every **PyAutoGalaxy** use case. - -- `The HowToGalaxy GitHub repository `_: a Jupyter notebook lecture series teaching galaxy modeling from the ground up. - -Core Aims -========= - -**PyAutoGalaxy** has three core aims: - -- **Big Data**: Scaling automated Sérsic fitting to extremely large datasets, *accelerated with JAX on GPUs and using tools like an SQL database to **build a scalable scientific workflow***. - -- **Model Complexity**: Fitting complex galaxy morphology models (e.g. Multi Gaussian Expansion, Shapelets, Ellipse Fitting, Irregular Meshes) that go beyond just simple Sérsic fitting. - -- **Data Variety**: Support for many data types (e.g. CCD imaging, interferometry, multi-band imaging) which can be fitted independently or simultaneously. - -Features -======== - -Core features include fully automated Bayesian model-fitting of galaxy two-dimensional surface brightness profiles, -support for dataset and interferometer datasets and comprehensive tools for simulating galaxy images. The software -places a focus on **big data** analysis, including support for hierarchical models that simultaneously fit thousands of -galaxies, massively parallel model-fitting and an SQLite3 database that allows large suites of modeling results to be -loaded, queried and analysed. - -The **HowToGalaxy** Jupyter notebook lectures, which live in their own -`PyAutoLabs/HowToGalaxy `_ repository, are written assuming no -previous knowledge about galaxy structure and teach a new user the theory and statistics required to analyse -galaxy data. Checkout `the howtogalaxy section of -the readthedocs `_. - -An overview of **PyAutoGalaxy**'s core features can be found in -the `overview section of the readthedocs `_. - -Galaxy Morphology & Structure -============================= - -The study of galaxy morphology aims to understand the different luminous structures that galaxies are composed of. -Using large CCD imaging datasets of galaxies observed at ultraviolet, optical and near-infrared wavelengths from -instruments like the Hubble Space Telescope (HST), Astronomers have uncovered the plentiful structures that make up -a galaxy (e.g. bars, bulges, disks and rings) and revealed that evolving galaxies transition from disk-like structures -to bulge-like elliptical galaxies. At sub-mm and radio wavelengths interferometer datasets from instruments like the -Atacama LAM (ALMA) have revealed the integral role that dust plays in forming a galaxy in the distant Universe, early -in its lifetime. Studies typically represent a galaxy's light using analytic functions such as the Sersic -profile, which quantify the global appearance of most galaxies into one of three groups: (i) bulge-like -structures which follow a dev Vaucouleurs profile; (ii) disk-like structures which follow an Exponential profile -or; (iii) irregular morphologies which are difficult to quantify with symmetric and smooth analytic profiles. Galaxies -are often composed of many sub-components which may be a combination of these different structures. - -In the next decade, wide field surveys such as Euclid, the Vera Rubin Observatory and Square Kilometer array are -poised to observe images of _billions_ of galaxies. Analysing these extremely large galaxy datasets demands -advanced Bayesian model-fitting techniques which can scale-up in a fully automated manner. Equally, the James Webb -Space Telescope, thirty-meter class ground telescopes and ?radio? will observe galaxies at an -unprecedented resolution and level of detail. This demands more flexible modeling techniques that can accurately -represent the complex irregular structures one such high resolution observations reveal. ``PyAutoGalaxy`` aims to meet -both these needs, by interfacing galaxy model-fitting with the probabilistic programming language ``PyAutoFit`` to -provide Bayesian fitting tools suited to big data analysis alongside image processing tools that represent irregular -galaxy structures using non-parametric models. - -How does PyAutoGalaxy Work? -=========================== - -At the heart of the `PyAutoGalaxy` API is the `Galaxy` object, which groups together one or more `LightProfile` objects -at an input redshift. Passing these objects a `Grid2D` returns an image of the galaxy(s), which can subsequently -be passed through `Operator` objects to apply a 2D convolution or Fast Fourier Transform and thereby compare -the `Galaxy`'s image to an imaging or interferometer dataset. The `inversion` package contains a range of non-parametric -models which fit a galaxy's light using a Bayesian linear matrix inversion. The `astropy` cosmology module is -used to handle unit conversions and calculations are optimized using the packages `NumPy` [@numpy], `numba` [@numba] -and `PyNUFFT` [@pynufft]. - -.. code-block:: python - - import autogalaxy as ag - import autogalaxy.plot as aplt - - """ - To describe the galaxy emission two-dimensional grids of (y,x) Cartesian - coordinates are used. - """ - grid = ag.Grid2D.uniform( - shape_native=(50, 50), - pixel_scales=0.05, # <- Conversion from pixel units to arc-seconds. - ) - - """ - The galaxy has an elliptical sersic light profile representing its bulge. - """ - bulge = ag.lp.Sersic( - centre=(0.0, 0.0), - ell_comps=ag.convert.ell_comps_from(axis_ratio=0.9, angle=45.0), - intensity=1.0, - effective_radius=0.6, - sersic_index=3.0, - ) - - """ - The galaxy also has an elliptical exponential disk - """ - disk = ag.lp.Exponential( - centre=(0.0, 0.0), - ell_comps=ag.convert.ell_comps_from(axis_ratio=0.7, angle=30.0), - intensity=0.5, - effective_radius=1.6, - ) - - """ - We combine the above light profiles to compose a galaxy at redshift 1.0. - """ - galaxy = ag.Galaxy(redshift=1.0, bulge=bulge, disk=disk) - - """ - We can use the grid and galaxies to perform many calculations, for example - plotting the image of the galaxies. - """ - galaxies_plotter = aplt.Galaxies(galaxies=[galaxy], grid=grid) - galaxies_plotter.figures_2d(image=True) - - -To perform model-fitting, `PyAutoGalaxy` adopts the probabilistic programming -language `PyAutoFit` (https://github.com/rhayes777/PyAutoFit). `PyAutoFit` allows users to compose a -model from `LightProfile` and `Galaxy` objects, customize the model parameterization and fit it to data via a -non-linear search (e.g., `dynesty` [@dynesty], `emcee` [@emcee], `PySwarms` [@pyswarms]). By composing a model with -`Pixelization` objects, the galaxy's light is reconstructed using a non-parametric rectangular -grid or Voronoi mesh that accounts for irregular galaxy morphologies. - -.. code-block:: python - - import autofit as af - import autogalaxy as ag - - import os - - """ - Load Imaging data of the galaxy from the dataset folder of the workspace. - """ - dataset = ag.Imaging.from_fits( - data_path="/path/to/dataset/image.fits", - noise_map_path="/path/to/dataset/noise_map.fits", - psf_path="/path/to/dataset/psf.fits", - pixel_scales=0.1, - ) - - """ - Create a mask for the data, which we setup as a 3.0" circle. - """ - mask = ag.Mask2D.circular( - shape_native=dataset.shape_native, pixel_scales=dataset.pixel_scales, radius=3.0 - ) - - """ - We model the galaxy using an Sersic LightProfile. - """ - light_profile = ag.lp.Sersic - - """ - We next setup this profile as model components whose parameters are free & fitted for - by setting up a Galaxy as a Model. - """ - galaxy_model = af.Model(ag.Galaxy, redshift=1.0, light=light_profile) - model = af.Collection(galaxy=galaxy_model) - - """ - We define the non-linear search used to fit the model to the data (in this case, Dynesty). - """ - search = af.Nautilus(name="search[example]", n_live=50) - - """ - We next set up the `Analysis`, which contains the `log likelihood function` that the - non-linear search calls to fit the lens model to the data. - """ - analysis = ag.AnalysisImaging(dataset=masked_dataset) - - """ - To perform the model-fit we pass the model and analysis to the search's fit method. This will - output results (e.g., dynesty samples, model parameters, visualization) to hard-disk. - """ - result = search.fit(model=model, analysis=analysis) - - """ - The results contain information on the fit, for example the maximum likelihood - model from the Dynesty parameter space search. - """ - print(result.samples.max_log_likelihood()) - -.. toctree:: - :caption: Overview: - :maxdepth: 1 - :hidden: - - overview/overview_1_start_here - overview/overview_2_new_user_guide - overview/overview_3_features - -.. toctree:: - :caption: Installation: - :maxdepth: 1 - :hidden: - - installation/overview - installation/conda - installation/pip - installation/numba - installation/source - installation/troubleshooting - -.. toctree:: - :caption: General: - :maxdepth: 1 - :hidden: - - general/workspace - general/configs - general/model_cookbook - general/likelihood_function - general/citations - general/credits - -.. toctree:: - :caption: Tutorials: - :maxdepth: 1 - :hidden: - - howtogalaxy/howtogalaxy - howtogalaxy/chapter_1_introduction - howtogalaxy/chapter_2_modeling - howtogalaxy/chapter_3_search_chaining - howtogalaxy/chapter_4_pixelizations - howtogalaxy/chapter_optional - -.. toctree:: - :caption: API Reference: - :maxdepth: 1 - :hidden: - - api/data - api/light - api/galaxy - api/fitting - api/modeling - api/pixelization - api/plot - api/source diff --git a/docs/installation/conda.rst b/docs/installation/conda.md similarity index 51% rename from docs/installation/conda.rst rename to docs/installation/conda.md index 9fe6af300..e32142cbd 100644 --- a/docs/installation/conda.rst +++ b/docs/installation/conda.md @@ -1,106 +1,101 @@ -.. _conda: - -Installation with conda -======================= - -Install -------- - -Installation via a conda environment circumvents compatibility issues when installing certain libraries. This guide -assumes you have a working installation of `conda `_. - -First, update conda: - -.. code-block:: bash - - conda update -n base -c defaults conda - -Next, create a conda environment (we name this ``autogalaxy`` to signify it is for the **PyAutoGalaxy** install): - -The command below creates this environment with Python 3.12: - -.. code-block:: bash - - conda create -n autogalaxy python=3.12 - -Activate the conda environment (you will have to do this every time you want to run **PyAutoGalaxy**): - -.. code-block:: bash - - conda activate autogalaxy - -We upgrade pip to ensure certain libraries install: - -.. code-block:: bash - - pip install --upgrade pip - -The latest version of **PyAutoGalaxy** is installed via pip as follows (the command ``--no-cache-dir`` prevents -caching issues impacting the installation): - -.. code-block:: bash - - pip install autogalaxy --no-cache-dir - -If pip prints warnings about dependency version conflicts, these can usually be ignored — the instructions below -will identify clearly if the installation is a success. - -If there are no errors **PyAutoGalaxy** is installed! - -If there is an error check out the `troubleshooting section `_. - -Workspace ---------- - -Next, clone the ``autogalaxy workspace`` (the line ``--depth 1`` clones only the most recent branch on -the ``autogalaxy_workspace``, reducing the download size): - -.. code-block:: bash - - cd /path/on/your/computer/you/want/to/put/the/autogalaxy_workspace - git clone https://github.com/Jammy2211/autogalaxy_workspace --depth 1 - cd autogalaxy_workspace - -Run the ``welcome.py`` script to get started! - -.. code-block:: bash - - python3 welcome.py - -It should be clear that **PyAutoGalaxy** runs without issue. - -If there is an error check out the `troubleshooting section `_. - -Numba ------ - -Numba (https://numba.pydata.org) is an optional library which makes **PyAutoGalaxy** run a lot faster, which we -strongly recommend users have installed. - -You can install numba via the following command: - -.. code-block:: bash - - pip install numba --no-cache-dir - -Some users have experienced difficulties installing numba, which is why it is an optional library. If your -installation is not successful, you can use **PyAutoGalaxy** without it installed for now, to familiarize yourself -with the software and determine if it is the right software for you. - -If you decide that **PyAutoGalaxy** is the right software, then I recommend you commit the time to getting a -successful numba install working, with more information provided `at this readthedocs page `_ - -Optional --------- - -For interferometer analysis there are two optional dependencies that must be installed via the commands: - -.. code-block:: bash - - pip install pynufft - -**PyAutoGalaxy** will run without these libraries and it is recommended that you only install them if you intend to -do interferometer analysis. - -If you run interferometer code a message explaining that you need to install these libraries will be printed, therefore -it is safe not to install them initially. \ No newline at end of file +(conda)= + +# Installation with conda + +## Install + +Installation via a conda environment circumvents compatibility issues when installing certain libraries. This guide +assumes you have a working installation of [conda](https://conda.io/miniconda.html). + +First, update conda: + +```bash +conda update -n base -c defaults conda +``` + +Next, create a conda environment (we name this `autogalaxy` to signify it is for the **PyAutoGalaxy** install): + +The command below creates this environment with Python 3.12: + +```bash +conda create -n autogalaxy python=3.12 +``` + +Activate the conda environment (you will have to do this every time you want to run **PyAutoGalaxy**): + +```bash +conda activate autogalaxy +``` + +We upgrade pip to ensure certain libraries install: + +```bash +pip install --upgrade pip +``` + +The latest version of **PyAutoGalaxy** is installed via pip as follows (the command `--no-cache-dir` prevents +caching issues impacting the installation): + +```bash +pip install autogalaxy --no-cache-dir +``` + +If pip prints warnings about dependency version conflicts, these can usually be ignored — the instructions below +will identify clearly if the installation is a success. + +If there are no errors **PyAutoGalaxy** is installed! + +If there is an error check out the [troubleshooting section](https://pyautogalaxy.readthedocs.io/en/latest/installation/troubleshooting.html). + +## Workspace + +Next, clone the `autogalaxy workspace` (the line `--depth 1` clones only the most recent branch on +the `autogalaxy_workspace`, reducing the download size): + +```bash +cd /path/on/your/computer/you/want/to/put/the/autogalaxy_workspace +git clone https://github.com/Jammy2211/autogalaxy_workspace --depth 1 +cd autogalaxy_workspace +``` + +Run the `welcome.py` script to get started! + +```bash +python3 welcome.py +``` + +It should be clear that **PyAutoGalaxy** runs without issue. + +If there is an error check out the [troubleshooting section](https://pyautogalaxy.readthedocs.io/en/latest/installation/troubleshooting.html). + +## Numba + +Numba () is an optional library which makes **PyAutoGalaxy** run a lot faster, which we +strongly recommend users have installed. + +You can install numba via the following command: + +```bash +pip install numba --no-cache-dir +``` + +Some users have experienced difficulties installing numba, which is why it is an optional library. If your +installation is not successful, you can use **PyAutoGalaxy** without it installed for now, to familiarize yourself +with the software and determine if it is the right software for you. + +If you decide that **PyAutoGalaxy** is the right software, then I recommend you commit the time to getting a +successful numba install working, with more information provided [at this readthedocs page](https://pyautogalaxy.readthedocs.io/en/latest/installation/numba.html) + +## Optional + +For interferometer analysis there are two optional dependencies that must be installed via the commands: + +```bash +pip install pynufft +``` + +**PyAutoGalaxy** will run without these libraries and it is recommended that you only install them if you intend to +do interferometer analysis. + +If you run interferometer code a message explaining that you need to install these libraries will be printed, therefore +it is safe not to install them initially. diff --git a/docs/installation/numba.rst b/docs/installation/numba.md similarity index 74% rename from docs/installation/numba.rst rename to docs/installation/numba.md index 132f50052..1a089e102 100644 --- a/docs/installation/numba.rst +++ b/docs/installation/numba.md @@ -1,23 +1,22 @@ -.. _numba: - -Numba -===== - -Numba (https://numba.pydata.org) is an optional library which makes **PyAutoGalaxy** run a lot faster, which we strongly -recommend all users have installed. - -Certain functionality (pixelized source reconstructions, linear light profiles) is disabled without numba installed -because it will have too slow run-times. - -However, some users have experienced difficulties installing numba, meaning they have been unable to try out -**PyAutoGalaxy** and determine if it the right software for them, before committing more time to installing numba -successfully. - -For this reason, numba is an optional installation, so that users can easily experiment and learn -the basic API. - -If you do not have numba installed, you can do so via pip as follows: - -.. code-block:: bash - - pip install numba \ No newline at end of file +(numba)= + +# Numba + +Numba () is an optional library which makes **PyAutoGalaxy** run a lot faster, which we strongly +recommend all users have installed. + +Certain functionality (pixelized source reconstructions, linear light profiles) is disabled without numba installed +because it will have too slow run-times. + +However, some users have experienced difficulties installing numba, meaning they have been unable to try out +**PyAutoGalaxy** and determine if it the right software for them, before committing more time to installing numba +successfully. + +For this reason, numba is an optional installation, so that users can easily experiment and learn +the basic API. + +If you do not have numba installed, you can do so via pip as follows: + +```bash +pip install numba +``` diff --git a/docs/installation/overview.md b/docs/installation/overview.md new file mode 100644 index 000000000..377c0fd69 --- /dev/null +++ b/docs/installation/overview.md @@ -0,0 +1,57 @@ +(overview)= + +# Overview + +**PyAutoGalaxy** requires Python 3.12 - 3.13 and supports the Linux, MacOS and Windows operating systems. + +**PyAutoGalaxy** can be installed via the Python distribution [Anaconda](https://www.anaconda.com/) or using +[PyPI](https://pypi.org/) to `pip install autogalaxy` into your Python distribution. + +We recommend Anaconda as it manages the installation of many major libraries (e.g. numpy, scipy, +matplotlib, etc.) making installation more straight forward. Windows users must use Anaconda. + +The installation guide for both approaches can be found at: + +- [Anaconda installation guide](https://pyautogalaxy.readthedocs.io/en/latest/installation/conda.html) +- [PyPI installation guide](https://pyautogalaxy.readthedocs.io/en/latest/installation/pip.html) + +Users who wish to build **PyAutoGalaxy** from source (e.g. via a `git clone`) should follow +our [building from source installation guide](https://pyautogalaxy.readthedocs.io/en/latest/installation/source.html). + +## Dependencies + +**PyAutoGalaxy** has the following dependencies: + +**PyAutoConf** + +**PyAutoFit** + +**PyAutoArray** + +**dynesty** + +**emcee** + +**PySwarms** + +**colossus**: + +**astropy** + +**corner.py** + +**matplotlib** + +**numba** + +**numpy** + +**scipy** + +**scikit-image**: + +**scikit-learn**: + +And the following optional dependencies: + +**pynufft**: diff --git a/docs/installation/overview.rst b/docs/installation/overview.rst deleted file mode 100644 index 2db3f9315..000000000 --- a/docs/installation/overview.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _overview: - -Overview -======== - -**PyAutoGalaxy** requires Python 3.12 - 3.13 and supports the Linux, MacOS and Windows operating systems. - -**PyAutoGalaxy** can be installed via the Python distribution `Anaconda `_ or using -`PyPI `_ to ``pip install autogalaxy`` into your Python distribution. - -We recommend Anaconda as it manages the installation of many major libraries (e.g. numpy, scipy, -matplotlib, etc.) making installation more straight forward. Windows users must use Anaconda. - -The installation guide for both approaches can be found at: - -- `Anaconda installation guide `_ - -- `PyPI installation guide `_ - -Users who wish to build **PyAutoGalaxy** from source (e.g. via a ``git clone``) should follow -our `building from source installation guide `_. - -Dependencies ------------- - -**PyAutoGalaxy** has the following dependencies: - -**PyAutoConf** https://github.com/rhayes777/PyAutoConf - -**PyAutoFit** https://github.com/rhayes777/PyAutoFit - -**PyAutoArray** https://github.com/Jammy2211/PyAutoArray - -**dynesty** https://github.com/joshspeagle/dynesty - -**emcee** https://github.com/dfm/emcee - -**PySwarms** https://github.com/ljvmiranda921/pyswarms - -**colossus**: https://bdiemer.bitbucket.io/colossus/ - -**astropy** https://www.astropy.org/ - -**corner.py** https://github.com/dfm/corner.py - -**matplotlib** https://matplotlib.org/ - -**numba** https://github.com/numba/numba - -**numpy** https://numpy.org/ - -**scipy** https://www.scipy.org/ - -**scikit-image**: https://github.com/scikit-image/scikit-image - -**scikit-learn**: https://github.com/scikit-learn/scikit-learn - -And the following optional dependencies: - -**pynufft**: https://github.com/jyhmiinlin/pynufft diff --git a/docs/installation/pip.md b/docs/installation/pip.md new file mode 100644 index 000000000..da5f63691 --- /dev/null +++ b/docs/installation/pip.md @@ -0,0 +1,104 @@ +(pip)= + +# Installation with pip + +:::{note} +**PyAutoGalaxy** requires **Python 3.12 or later**. If you are on Python +3.9, 3.10, or 3.11, `pip install autogalaxy` will fail with a "no matching +distribution" error. Upgrade Python to 3.12+ before installing. +::: + +## Install + +We strongly recommend that you install **PyAutoGalaxy** in a +[Python virtual environment](https://www.geeksforgeeks.org/python-virtual-environment/), with the link attached +describing what a virtual environment is and how to create one. + +We upgrade pip to ensure certain libraries install: + +```bash +pip install --upgrade pip +``` + +The latest version of **PyAutoGalaxy** is installed via pip as follows (specifying the version as shown below ensures +the installation has clean dependencies): + +```bash +pip install autogalaxy +``` + +If pip prints warnings about dependency version conflicts, these can usually be ignored — the instructions below +will identify clearly if the installation is a success. + +If there are no errors **PyAutoGalaxy** is installed! + +If there is an error check out the [troubleshooting section](https://pyautogalaxy.readthedocs.io/en/latest/installation/troubleshooting.html). + +## Workspace + +Next, clone the `autogalaxy workspace` (the line `--depth 1` clones only the most recent branch on +the `autogalaxy_workspace`, reducing the download size): + +```bash +cd /path/on/your/computer/you/want/to/put/the/autogalaxy_workspace +git clone https://github.com/Jammy2211/autogalaxy_workspace --depth 1 +cd autogalaxy_workspace +``` + +Run the `welcome.py` script to get started! + +```bash +python3 welcome.py +``` + +It should be clear that **PyAutoGalaxy** runs without issue. + +If there is an error check out the [troubleshooting section](https://pyautogalaxy.readthedocs.io/en/latest/installation/troubleshooting.html). + +## Numba + +Numba () is an optional library which makes **PyAutoGalaxy** run a lot faster, which we +strongly recommend users have installed. + +You can install numba via the following command: + +```bash +pip install numba +``` + +Some users have experienced difficulties installing numba, which is why it is an optional library. If your +installation is not successful, you can use **PyAutoGalaxy** without it installed for now, to familiarize yourself +with the software and determine if it is the right software for you. + +If you decide that **PyAutoGalaxy** is the right software, then I recommend you commit the time to getting a +successful numba install working, with more information provided [at this readthedocs page](https://pyautogalaxy.readthedocs.io/en/latest/installation/numba.html) + +## Optional + +For interferometer analysis there are two optional dependencies that must be installed via the commands: + +```bash +pip install pynufft +``` + +**PyAutoGalaxy** will run without these libraries and it is recommended that you only install them if you intend to +do interferometer analysis. + +If you run interferometer code a message explaining that you need to install these libraries will be printed, therefore +it is safe not to install them initially. + +## Legacy Python versions + +We dropped support for Python 3.9, 3.10, and 3.11 in release `2026.4.5.3` +(April 2026). Pre-`2026.4.5.3` releases on PyPI have been yanked, so they +will not install via the standard `pip install autogalaxy` command. + +If you have an existing project that requires a pre-`2026.4.5.3` version, +you can still install it explicitly by pinning the version, e.g.: + +```bash +pip install autogalaxy==2025.10.6.1 +``` + +Yanked releases remain available for explicit pins; only resolver-driven +fallback is blocked. diff --git a/docs/installation/pip.rst b/docs/installation/pip.rst deleted file mode 100644 index 50b5351c4..000000000 --- a/docs/installation/pip.rst +++ /dev/null @@ -1,109 +0,0 @@ -.. _pip: - -Installation with pip -===================== - -.. note:: - **PyAutoGalaxy** requires **Python 3.12 or later**. If you are on Python - 3.9, 3.10, or 3.11, ``pip install autogalaxy`` will fail with a "no matching - distribution" error. Upgrade Python to 3.12+ before installing. - -Install -------- - -We strongly recommend that you install **PyAutoGalaxy** in a -`Python virtual environment `_, with the link attached -describing what a virtual environment is and how to create one. - -We upgrade pip to ensure certain libraries install: - -.. code-block:: bash - - pip install --upgrade pip - -The latest version of **PyAutoGalaxy** is installed via pip as follows (specifying the version as shown below ensures -the installation has clean dependencies): - -.. code-block:: bash - - pip install autogalaxy - -If pip prints warnings about dependency version conflicts, these can usually be ignored — the instructions below -will identify clearly if the installation is a success. - -If there are no errors **PyAutoGalaxy** is installed! - -If there is an error check out the `troubleshooting section `_. - -Workspace ---------- - -Next, clone the ``autogalaxy workspace`` (the line ``--depth 1`` clones only the most recent branch on -the ``autogalaxy_workspace``, reducing the download size): - -.. code-block:: bash - - cd /path/on/your/computer/you/want/to/put/the/autogalaxy_workspace - git clone https://github.com/Jammy2211/autogalaxy_workspace --depth 1 - cd autogalaxy_workspace - -Run the ``welcome.py`` script to get started! - -.. code-block:: bash - - python3 welcome.py - -It should be clear that **PyAutoGalaxy** runs without issue. - -If there is an error check out the `troubleshooting section `_. - -Numba ------ - -Numba (https://numba.pydata.org) is an optional library which makes **PyAutoGalaxy** run a lot faster, which we -strongly recommend users have installed. - -You can install numba via the following command: - -.. code-block:: bash - - pip install numba - -Some users have experienced difficulties installing numba, which is why it is an optional library. If your -installation is not successful, you can use **PyAutoGalaxy** without it installed for now, to familiarize yourself -with the software and determine if it is the right software for you. - -If you decide that **PyAutoGalaxy** is the right software, then I recommend you commit the time to getting a -successful numba install working, with more information provided `at this readthedocs page `_ - -Optional --------- - -For interferometer analysis there are two optional dependencies that must be installed via the commands: - -.. code-block:: bash - - pip install pynufft - -**PyAutoGalaxy** will run without these libraries and it is recommended that you only install them if you intend to -do interferometer analysis. - -If you run interferometer code a message explaining that you need to install these libraries will be printed, therefore -it is safe not to install them initially. - -Legacy Python versions ----------------------- - -We dropped support for Python 3.9, 3.10, and 3.11 in release ``2026.4.5.3`` -(April 2026). Pre-``2026.4.5.3`` releases on PyPI have been yanked, so they -will not install via the standard ``pip install autogalaxy`` command. - -If you have an existing project that requires a pre-``2026.4.5.3`` version, -you can still install it explicitly by pinning the version, e.g.: - -.. code-block:: bash - - pip install autogalaxy==2025.10.6.1 - -Yanked releases remain available for explicit pins; only resolver-driven -fallback is blocked. \ No newline at end of file diff --git a/docs/installation/source.md b/docs/installation/source.md new file mode 100644 index 000000000..6ae981aad --- /dev/null +++ b/docs/installation/source.md @@ -0,0 +1,150 @@ +(source)= + +# Building From Source + +Building from source means that you clone (or fork) the **PyAutoGalaxy** GitHub repository and run **PyAutoGalaxy** from +there. Unlike `conda` and `pip` this provides a build of the source code that you can edit and change, to +contribute the development **PyAutoGalaxy** or experiment with yourself! + +A large amount of **PyAutoGalaxy** functionality is contained in its parent projects: + +**PyAutoFit** + +**PyAutoArray** + +If you wish to build from source all code you may need to build from source these 3 additional +projects. We include below instructions for building just **PyAutoGalaxy** from source or building all projects. + +## Building Only PyAutoGalaxy + +We upgrade pip to ensure certain libraries install: + +```bash +pip install --upgrade pip +``` + +First, clone (or fork) the **PyAutoGalaxy** GitHub repository: + +```bash +git clone https://github.com/Jammy2211/PyAutoGalaxy +``` + +Next, install the **PyAuto** parent projects via pip: + +```bash +pip install autoconf +pip install autofit +pip install autoarray +``` + +Next, install the **PyAutoGalaxy** dependencies via pip: + +```bash +pip install -r PyAutoGalaxy/requirements.txt +``` + +Next, install the optional dependency numba via pip (see [this link](https://pyautogalaxy.readthedocs.io/en/latest/installation/numba.html) for a description of numba): + +```bash +pip install numba +``` + +For unit tests to pass you will also need the following optional requirements: + +```bash +pip install pynufft +``` + +If you are using a `conda` environment, add the source repository as follows: + +\[NOTE: Certain versions of conda use the command `conda develop` (without a dash) instead of those shown below.\] + +```bash +conda-develop PyAutoGalaxy +``` + +Alternatively, if you are using a Python environment include the **PyAutoGalaxy** source repository in your PYTHONPATH +(noting that you must replace the text `/path/to` with the path to the **PyAutoGalaxy** directory on your computer): + +```bash +export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoGalaxy +``` + +Finally, check the **PyAutoGalaxy** unit tests run and pass (you may need to install pytest via `pip install pytest`): + +```bash +cd /path/to/PyAutoGalaxy +python3 -m pytest +``` + +## Building All Projects + +We upgrade pip to ensure certain libraries install: + +```bash +pip install --upgrade pip +``` + +First, clone (or fork) all 4 GitHub repositories: + +```bash +git clone https://github.com/rhayes777/PyAutoFit +git clone https://github.com/Jammy2211/PyAutoArray +git clone https://github.com/Jammy2211/PyAutoGalaxy +``` + +Next, install **PyAutoConf** via pip: + +```bash +pip install autoconf +``` + +Next, install the source build dependencies of each project via pip: + +```bash +pip install -r PyAutoFit/requirements.txt +pip install -r PyAutoArray/requirements.txt +pip install -r PyAutoGalaxy/requirements.txt +``` + +Next, install the optional dependency numba via pip (see [this link](https://pyautogalaxy.readthedocs.io/en/latest/installation/numba.html) for a description of numba): + +```bash +pip install numba +``` + +For unit tests to pass you will also need the following optional requirements: + +```bash +pip install -r PyAutoArray/optional_requirements.txt +``` + +If you are using a `conda` environment, add each source repository as follows: + +\[NOTE: Certain versions of conda use the command `conda develop` (without a dash) instead of those shown below.\] + +```bash +conda-develop PyAutoFit +conda-develop PyAutoArray +conda-develop PyAutoGalaxy +``` + +Alternatively, if you are using a Python environment include each source repository in your PYTHONPATH +(noting that you must replace the text `/path/to` with the path to the each directory on your computer): + +```bash +export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoFit +export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoArray +export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoGalaxy +``` + +Finally, check the unit tests run and pass for each project (you may need to install pytest via `pip install pytest`): + +```bash +cd /path/to/PyAutoFit +python3 -m pytest +cd ../PyAutoArray +python3 -m pytest +cd ../PyAutoGalaxy +python3 -m pytest +``` diff --git a/docs/installation/source.rst b/docs/installation/source.rst deleted file mode 100644 index 5028ca403..000000000 --- a/docs/installation/source.rst +++ /dev/null @@ -1,154 +0,0 @@ -.. _source: - -Building From Source -==================== - -Building from source means that you clone (or fork) the **PyAutoGalaxy** GitHub repository and run **PyAutoGalaxy** from -there. Unlike ``conda`` and ``pip`` this provides a build of the source code that you can edit and change, to -contribute the development **PyAutoGalaxy** or experiment with yourself! - -A large amount of **PyAutoGalaxy** functionality is contained in its parent projects: - -**PyAutoFit** https://github.com/rhayes777/PyAutoFit - -**PyAutoArray** https://github.com/Jammy2211/PyAutoArray - -If you wish to build from source all code you may need to build from source these 3 additional -projects. We include below instructions for building just **PyAutoGalaxy** from source or building all projects. - -Building Only PyAutoGalaxy --------------------------- - -We upgrade pip to ensure certain libraries install: - -.. code-block:: bash - - pip install --upgrade pip - -First, clone (or fork) the **PyAutoGalaxy** GitHub repository: - -.. code-block:: bash - - git clone https://github.com/Jammy2211/PyAutoGalaxy - -Next, install the **PyAuto** parent projects via pip: - -.. code-block:: bash - - pip install autoconf - pip install autofit - pip install autoarray - -Next, install the **PyAutoGalaxy** dependencies via pip: - -.. code-block:: bash - - pip install -r PyAutoGalaxy/requirements.txt - -Next, install the optional dependency numba via pip (see `this link `_ for a description of numba): - -.. code-block:: bash - - pip install numba - -For unit tests to pass you will also need the following optional requirements: - -.. code-block:: bash - - pip install pynufft - -If you are using a ``conda`` environment, add the source repository as follows: - -[NOTE: Certain versions of conda use the command ``conda develop`` (without a dash) instead of those shown below.] - -.. code-block:: bash - - conda-develop PyAutoGalaxy - -Alternatively, if you are using a Python environment include the **PyAutoGalaxy** source repository in your PYTHONPATH -(noting that you must replace the text ``/path/to`` with the path to the **PyAutoGalaxy** directory on your computer): - -.. code-block:: bash - - export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoGalaxy - -Finally, check the **PyAutoGalaxy** unit tests run and pass (you may need to install pytest via ``pip install pytest``): - -.. code-block:: bash - - cd /path/to/PyAutoGalaxy - python3 -m pytest - - -Building All Projects ---------------------- - -We upgrade pip to ensure certain libraries install: - -.. code-block:: bash - - pip install --upgrade pip - -First, clone (or fork) all 4 GitHub repositories: - -.. code-block:: bash - - git clone https://github.com/rhayes777/PyAutoFit - git clone https://github.com/Jammy2211/PyAutoArray - git clone https://github.com/Jammy2211/PyAutoGalaxy - -Next, install **PyAutoConf** via pip: - -.. code-block:: bash - - pip install autoconf - -Next, install the source build dependencies of each project via pip: - -.. code-block:: bash - - pip install -r PyAutoFit/requirements.txt - pip install -r PyAutoArray/requirements.txt - pip install -r PyAutoGalaxy/requirements.txt - -Next, install the optional dependency numba via pip (see `this link `_ for a description of numba): - -.. code-block:: bash - - pip install numba - -For unit tests to pass you will also need the following optional requirements: - -.. code-block:: bash - - pip install -r PyAutoArray/optional_requirements.txt - -If you are using a ``conda`` environment, add each source repository as follows: - -[NOTE: Certain versions of conda use the command ``conda develop`` (without a dash) instead of those shown below.] - -.. code-block:: bash - - conda-develop PyAutoFit - conda-develop PyAutoArray - conda-develop PyAutoGalaxy - -Alternatively, if you are using a Python environment include each source repository in your PYTHONPATH -(noting that you must replace the text ``/path/to`` with the path to the each directory on your computer): - -.. code-block:: bash - - export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoFit - export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoArray - export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoGalaxy - -Finally, check the unit tests run and pass for each project (you may need to install pytest via ``pip install pytest``): - -.. code-block:: bash - - cd /path/to/PyAutoFit - python3 -m pytest - cd ../PyAutoArray - python3 -m pytest - cd ../PyAutoGalaxy - python3 -m pytest \ No newline at end of file diff --git a/docs/installation/troubleshooting.md b/docs/installation/troubleshooting.md new file mode 100644 index 000000000..028a902d8 --- /dev/null +++ b/docs/installation/troubleshooting.md @@ -0,0 +1,69 @@ +(troubleshooting)= + +# Troubleshooting + +## Pip Version + +If an error message appears after trying to run `pip install autogalaxy` first make sure you are using +the latest version of pip. + +```bash +pip install --upgrade pip +pip3 install --upgrade pip +``` + +## Pip / Conda + +If you are trying to [install via pip](https://pyautolens.readthedocs.io/en/latest/installation/pip.html) but +still haing issues, we recommend you try to [install via conda](https://pyautogalaxy.readthedocs.io/en/latest/installation/conda.html) +instead, or visa versa. + +## Support + +If you are still having issues with installation, please raise an issue on the +[PyAutoGalaxy issues page](https://github.com/Jammy2211/PyAutoGalaxy/issues) with a description of the +problem and your system setup (operating system, Python version, etc.). + +## Current Working Directory + +**PyAutoGalaxy** scripts assume that the `autogalaxy_workspace` directory is the Python working directory. This means +that, when you run an example script, you should run it from the `autogalaxy_workspace` as follows: + +```bash +cd path/to/autogalaxy_workspace (if you are not already in the autogalaxy_workspace). +python3 examples/model/beginner/mass_total__source_lp.py +``` + +The reasons for this are so that **PyAutoGalaxy** can: + +> - Load configuration settings from config files in the `autogalaxy_workspace/config` folder. +> - Load example data from the `autogalaxy_workspace/dataset` folder. +> - Output the results of models fits to your hard-disk to the `autogalaxy/output` folder. + +If you have any errors relating to importing modules, loading data or outputting results it is likely because you +are not running the script with the `autogalaxy_workspace` as the working directory! + +## Matplotlib Backend + +Matplotlib uses the default backend on your computer, as set in the config file: + +```bash +autogalaxy_workspace/config/visualize/general.yaml +``` + +If unchanged, the backend is set to 'default', meaning it will use the backend automatically set up for Python on +your system. + +```bash +general: + backend: default +``` + +There have been reports that using the default backend causes crashes when running the test script below (either the +code crashes without a error or your computer restarts). If this happens, change the config's backend until the test +works (TKAgg has worked on Linux machines, Qt5Agg has worked on new MACs). For example: + +```bash +general: + backend: TKAgg +``` diff --git a/docs/installation/troubleshooting.rst b/docs/installation/troubleshooting.rst deleted file mode 100644 index b8724e3ae..000000000 --- a/docs/installation/troubleshooting.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _troubleshooting: - -Troubleshooting -=============== - -Pip Version ------------ - -If an error message appears after trying to run ``pip install autogalaxy`` first make sure you are using -the latest version of pip. - -.. code-block:: bash - - pip install --upgrade pip - pip3 install --upgrade pip - -Pip / Conda ------------ - -If you are trying to `install via pip `_ but -still haing issues, we recommend you try to `install via conda `_ -instead, or visa versa. - -Support -------- - -If you are still having issues with installation, please raise an issue on the -`PyAutoGalaxy issues page `_ with a description of the -problem and your system setup (operating system, Python version, etc.). - -Current Working Directory -------------------------- - -**PyAutoGalaxy** scripts assume that the ``autogalaxy_workspace`` directory is the Python working directory. This means -that, when you run an example script, you should run it from the ``autogalaxy_workspace`` as follows: - -.. code-block:: bash - - cd path/to/autogalaxy_workspace (if you are not already in the autogalaxy_workspace). - python3 examples/model/beginner/mass_total__source_lp.py - -The reasons for this are so that **PyAutoGalaxy** can: - - - Load configuration settings from config files in the ``autogalaxy_workspace/config`` folder. - - Load example data from the ``autogalaxy_workspace/dataset`` folder. - - Output the results of models fits to your hard-disk to the ``autogalaxy/output`` folder. - -If you have any errors relating to importing modules, loading data or outputting results it is likely because you -are not running the script with the ``autogalaxy_workspace`` as the working directory! - -Matplotlib Backend ------------------- - -Matplotlib uses the default backend on your computer, as set in the config file: - -.. code-block:: bash - - autogalaxy_workspace/config/visualize/general.yaml - -If unchanged, the backend is set to 'default', meaning it will use the backend automatically set up for Python on -your system. - -.. code-block:: bash - - general: - backend: default - -There have been reports that using the default backend causes crashes when running the test script below (either the -code crashes without a error or your computer restarts). If this happens, change the config's backend until the test -works (TKAgg has worked on Linux machines, Qt5Agg has worked on new MACs). For example: - -.. code-block:: bash - - general: - backend: TKAgg diff --git a/docs/overview/overview_1_start_here.rst b/docs/overview/overview_1_start_here.md similarity index 51% rename from docs/overview/overview_1_start_here.rst rename to docs/overview/overview_1_start_here.md index e61d29daf..0ec100d22 100644 --- a/docs/overview/overview_1_start_here.rst +++ b/docs/overview/overview_1_start_here.md @@ -1,303 +1,294 @@ -.. _overview_1_start_here: - -Start Here -========== - -**PyAutoGalaxy** is software for analysing the morphologies and structures of galaxies: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/paper/hstcombined.png - :width: 400 - :alt: Alternative text - -**PyAutoGalaxy** has three core aims: - -- **Big Data**: Scaling automated Sérsic fitting to extremely large datasets, *accelerated with JAX on GPUs and using tools like an SQL database to **build a scalable scientific workflow***. - -- **Model Complexity**: Fitting complex galaxy morphology models (e.g. Multi Gaussian Expansion, Shapelets, Ellipse Fitting, Irregular Meshes) that go beyond just simple Sérsic fitting. - -- **Data Variety**: Support for many data types (e.g. CCD imaging, interferometry, multi-band imaging) which can be fitted independently or simultaneously. - -This overview gives an overview of **PyAutoGalaxy**'s API, core features and details of the autogalaxy_workspace. - -Imports -------- - -Lets first import autogalaxy, its plotting module and the other libraries we'll need. - -You'll see these imports in the majority of workspace examples. - -.. code:: python - - import autogalaxy as ag - import autogalaxy.plot as aplt - - import matplotlib.pyplot as plt - from os import path - -Lets illustrate a simple galaxy structure calculations creating an an image of a galaxy using a light profile. - -Grid ----- - -The emission of light from a galaxy is described using the ``Grid2D`` data structure, which is two-dimensional -Cartesian grids of (y,x) coordinates where the light profile of the galaxy is evaluated on the grid. - -We make and plot a uniform Cartesian grid: - -.. code:: python - - grid = ag.Grid2D.uniform( - shape_native=(150, 150), # The [pixels x pixels] shape of the grid in 2D. - pixel_scales=0.05, # The pixel-scale describes the conversion from pixel units to arc-seconds. - ) - - aplt.plot_grid(grid=grid, title="Uniform Grid") - -The ``Grid2D`` looks like this: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/0_grid.png - :width: 600 - :alt: Alternative text - -Light Profiles --------------- - -Our aim is to create an image of the morphological structures that make up a galaxy. - -This uses analytic functions representing a galaxy's light, referred to as ``LightProfile`` objects. - -The most common light profile in Astronomy is the elliptical Sersic, which we create an instance of below: - -.. code:: python - - sersic_light_profile = ag.lp.Sersic( - centre=(0.0, 0.0), # The light profile centre [units of arc-seconds]. - ell_comps=( - 0.2, - 0.1, - ), # The light profile elliptical components [can be converted to axis-ratio and position angle]. - intensity=0.005, # The overall intensity normalisation [units arbitrary and are matched to the data]. - effective_radius=2.0, # The effective radius containing half the profile's total luminosity [units of arc-seconds]. - sersic_index=4.0, # Describes the profile's shape [higher value -> more concentrated profile]. - ) - -By passing the light profile the ``grid``, we evaluate the light emitted at every (y,x) coordinate and therefore create -an image of the Sersic light profile. - -.. code:: python - - image = sersic_light_profile.image_2d_from(grid=grid) - -Plotting --------- - -In-built plotting methods are provided for plotting objects and their properties, like the image of -a light profile we just created. - -By using ``aplt.plot_array`` to plot the light profile's image, the figure is improved. - -Its axis units are scaled to arc-seconds, a color-bar is added, descriptive labels are included, etc. - -The plot module is highly customizable and designed to make it straight forward to create clean and informative figures -for fits to large datasets. - -.. code:: python - - aplt.plot_array(array=sersic_light_profile.image_2d_from(grid=grid), title="Sersic Light Profile Image") - -The light profile appears as follows: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/1_image_2d.png - :width: 600 - :alt: Alternative text - -Galaxy ------- - -A ``Galaxy`` object is a collection of light profiles at a specific redshift. - -This object is highly extensible and is what ultimately allows us to fit complex models to galaxy images. - -Below, we combine the Sersic light profile above with an Exponential light profile to create a galaxy containing both -a bulge and disk component. - -.. code:: python - - exponential_light_profile = ag.lp.Exponential( - centre=(0.0, 0.0), ell_comps=(0.1, 0.0), intensity=0.1, effective_radius=0.5 - ) - - galaxy = ag.Galaxy( - redshift=0.5, bulge=sersic_light_profile, disk=exponential_light_profile - ) - - -We can plot the image of the galaxy, which is the sum of its bulge and disk light profiles: - -.. code:: python - - aplt.plot_array(array=galaxy.image_2d_from(grid=grid), title="Galaxy Image") - -The galaxy, with both a bulge and disk, appears as follows: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/2_image_2d.png - :width: 600 - :alt: Alternative text - -The individual light profiles of the galaxy can be plotted on a subplot: - -.. code:: python - - aplt.subplot_galaxy_light_profiles(galaxy=galaxy, grid=grid) - -The light profiles appear as follows: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/3_subplot_image.png - :width: 600 - :alt: Alternative text - - -Galaxies --------- - -The ``Galaxies`` object is a collection of galaxies at the same redshift. - -In a moment, we will see it is integral to the model-fitting API. - -For now, lets use it to create an image of a pair of merging galaxies, noting that a more concise API for creating -the galaxy is used below where the ``Sersic`` is passed directly to the ``Galaxy`` object. - -.. code:: python - - galaxy_1 = ag.Galaxy( - redshift=0.5, - bulge=ag.lp.Sersic( - centre=(0.5, 0.2), intensity=1.0, effective_radius=1.0, sersic_index=2.0 - ), - ) - - galaxies = ag.Galaxies( - galaxies=[galaxy, galaxy_1], - ) - - aplt.plot_array(array=galaxies.image_2d_from(grid=grid), title="Galaxies Image") - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/4_image_2d.png - :width: 600 - :alt: Alternative text - -Units ------ - -The units used throughout the galaxy structure literature vary, therefore lets quickly describe the units used in -**PyAutoGalaxy**. - -Most distance quantities, like an ``effective_radius`` are quantities in terms of angles, which are defined in units -of arc-seconds. To convert these to physical units (e.g. kiloparsecs), we use the redshift of the galaxy and an -input cosmology. A run through of all normal unit conversions is given in guides in the workspace outlined below. - -The use of angles in arc-seconds has an important property, it means that calculations are independent of -the galaxy's redshifts and the input cosmology. This has a number of benefits, for example it makes it straight -forward to compare the properties of different galaxies even when the redshifts of the galaxies are unknown. - -Extensibility -------------- - -All of the objects we've introduced so far are highly extensible, for example a galaxy can be made up of any number of -light profiles and many galaxy objects can be combined into a galaxies object. - -To further illustrate this, we create a merging galaxy system with 4 star forming clumps of light, using a -``SersicSph`` profile to make each spherical. - -.. code:: python - - galaxy_0 = ag.Galaxy( - redshift=0.5, - bulge=ag.lp.Sersic( - centre=(0.0, 0.0), - ell_comps=ag.convert.ell_comps_from(axis_ratio=0.9, angle=45.0), - intensity=0.2, - effective_radius=0.8, - sersic_index=4.0, - ), - disk=ag.lp.Exponential( - centre=(0.0, 0.0), - ell_comps=ag.convert.ell_comps_from(axis_ratio=0.7, angle=30.0), - intensity=0.1, - effective_radius=1.6, - ), - extra_galaxy_0=ag.lp.SersicSph(centre=(1.0, 1.0), intensity=0.5, effective_radius=0.2), - extra_galaxy_1=ag.lp.SersicSph(centre=(0.5, 0.8), intensity=0.5, effective_radius=0.2), - extra_galaxy_2=ag.lp.SersicSph(centre=(-1.0, -0.7), intensity=0.5, effective_radius=0.2), - extra_galaxy_3=ag.lp.SersicSph(centre=(-1.0, 0.4), intensity=0.5, effective_radius=0.2), - ) - - galaxy_1 = ag.Galaxy( - redshift=0.5, - bulge=ag.lp.Sersic( - centre=(0.0, 1.0), - ell_comps=(0.0, 0.1), - intensity=0.1, - effective_radius=0.6, - sersic_index=3.0, - ), - ) - - galaxies = ag.Galaxies(galaxies=[galaxy_0, galaxy_1]) - - aplt.plot_array(array=galaxies.image_2d_from(grid=grid), title="Galaxies Image") - -The image of the merging galaxy system appears as follows: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/5_image_2d.png - :width: 600 - :alt: Alternative text - -Galaxy Modeling ---------------- - -Galaxy modeling is the process of fitting a physical model to imaging data in order to infer the structural -and photometric properties of galaxies, such as their light distribution, size, shape, and orientation. - -The primary goal of **PyAutoGalaxy** is to make galaxy modeling **simple, scalable to large datasets, and fast**, -with GPU acceleration provided via JAX. - -The animation below illustrates the galaxy modeling workflow. Many models are fitted to the data iteratively, -progressively improving the quality of the fit until the model closely reproduces the observed image. - -NOTE: Placeholder showing strong lens modeling animation used currently. - -.. image:: https://github.com/Jammy2211/auto_files/blob/main/lensmodel.gif?raw=true - :width: 600 - -**Credit: Amy Etherington** - -The next documentation page guides you through galaxy modeling for a variety of data types (e.g. CCD imaging at -different resolutions) and scientific use-cases (e.g. galaxy morphology studies, bulge–disk decomposition). - -Simulations ------------ - -Simulating galaxy images is often essential, for example to: - -- Practice galaxy modeling before working with real data. -- Generate large training sets (e.g. for machine learning). -- Test galaxy formation and structural models in a fully controlled environment. - -The next documentation page guides you through how to simulate galaxies for different types of data -(e.g. CCD imaging) and different modeling goals (e.g. single-component galaxies, multi-component systems). - - -Wrap Up -------- - -This completes the introduction to **PyAutoGalaxy**, including a brief overview of the core API for galaxy -light profile calculations, galaxy modeling, and data simulation. - -Different users will be interested in galaxies across a range of physical scales and scientific applications -(e.g. detailed structural studies, population analyses, or multi-wavelength modeling) and using different -types of data (e.g. CCD imaging or interferometer observations). - -The autogalaxy_workspace repository contains a wide range of examples and tutorials covering these use cases. -The next documentation page helps new users identify the most appropriate starting point based on their -scientific goals. \ No newline at end of file +(overview-1-start-here)= + +# Start Here + +**PyAutoGalaxy** is software for analysing the morphologies and structures of galaxies: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/paper/hstcombined.png +:alt: Alternative text +:width: 400 +``` + +**PyAutoGalaxy** has three core aims: + +- **Big Data**: Scaling automated Sérsic fitting to extremely large datasets, *accelerated with JAX on GPUs and using tools like an SQL database to \*\*build a scalable scientific workflow\*\**. +- **Model Complexity**: Fitting complex galaxy morphology models (e.g. Multi Gaussian Expansion, Shapelets, Ellipse Fitting, Irregular Meshes) that go beyond just simple Sérsic fitting. +- **Data Variety**: Support for many data types (e.g. CCD imaging, interferometry, multi-band imaging) which can be fitted independently or simultaneously. + +This overview gives an overview of **PyAutoGalaxy**'s API, core features and details of the autogalaxy_workspace. + +## Imports + +Lets first import autogalaxy, its plotting module and the other libraries we'll need. + +You'll see these imports in the majority of workspace examples. + +```python +import autogalaxy as ag +import autogalaxy.plot as aplt + +import matplotlib.pyplot as plt +from os import path +``` + +Lets illustrate a simple galaxy structure calculations creating an an image of a galaxy using a light profile. + +## Grid + +The emission of light from a galaxy is described using the `Grid2D` data structure, which is two-dimensional +Cartesian grids of (y,x) coordinates where the light profile of the galaxy is evaluated on the grid. + +We make and plot a uniform Cartesian grid: + +```python +grid = ag.Grid2D.uniform( + shape_native=(150, 150), # The [pixels x pixels] shape of the grid in 2D. + pixel_scales=0.05, # The pixel-scale describes the conversion from pixel units to arc-seconds. +) + +aplt.plot_grid(grid=grid, title="Uniform Grid") +``` + +The `Grid2D` looks like this: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/0_grid.png +:alt: Alternative text +:width: 600 +``` + +## Light Profiles + +Our aim is to create an image of the morphological structures that make up a galaxy. + +This uses analytic functions representing a galaxy's light, referred to as `LightProfile` objects. + +The most common light profile in Astronomy is the elliptical Sersic, which we create an instance of below: + +```python +sersic_light_profile = ag.lp.Sersic( + centre=(0.0, 0.0), # The light profile centre [units of arc-seconds]. + ell_comps=( + 0.2, + 0.1, + ), # The light profile elliptical components [can be converted to axis-ratio and position angle]. + intensity=0.005, # The overall intensity normalisation [units arbitrary and are matched to the data]. + effective_radius=2.0, # The effective radius containing half the profile's total luminosity [units of arc-seconds]. + sersic_index=4.0, # Describes the profile's shape [higher value -> more concentrated profile]. +) +``` + +By passing the light profile the `grid`, we evaluate the light emitted at every (y,x) coordinate and therefore create +an image of the Sersic light profile. + +```python +image = sersic_light_profile.image_2d_from(grid=grid) +``` + +## Plotting + +In-built plotting methods are provided for plotting objects and their properties, like the image of +a light profile we just created. + +By using `aplt.plot_array` to plot the light profile's image, the figure is improved. + +Its axis units are scaled to arc-seconds, a color-bar is added, descriptive labels are included, etc. + +The plot module is highly customizable and designed to make it straight forward to create clean and informative figures +for fits to large datasets. + +```python +aplt.plot_array(array=sersic_light_profile.image_2d_from(grid=grid), title="Sersic Light Profile Image") +``` + +The light profile appears as follows: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/1_image_2d.png +:alt: Alternative text +:width: 600 +``` + +## Galaxy + +A `Galaxy` object is a collection of light profiles at a specific redshift. + +This object is highly extensible and is what ultimately allows us to fit complex models to galaxy images. + +Below, we combine the Sersic light profile above with an Exponential light profile to create a galaxy containing both +a bulge and disk component. + +```python +exponential_light_profile = ag.lp.Exponential( + centre=(0.0, 0.0), ell_comps=(0.1, 0.0), intensity=0.1, effective_radius=0.5 +) + +galaxy = ag.Galaxy( + redshift=0.5, bulge=sersic_light_profile, disk=exponential_light_profile +) +``` + +We can plot the image of the galaxy, which is the sum of its bulge and disk light profiles: + +```python +aplt.plot_array(array=galaxy.image_2d_from(grid=grid), title="Galaxy Image") +``` + +The galaxy, with both a bulge and disk, appears as follows: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/2_image_2d.png +:alt: Alternative text +:width: 600 +``` + +The individual light profiles of the galaxy can be plotted on a subplot: + +```python +aplt.subplot_galaxy_light_profiles(galaxy=galaxy, grid=grid) +``` + +The light profiles appear as follows: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/3_subplot_image.png +:alt: Alternative text +:width: 600 +``` + +## Galaxies + +The `Galaxies` object is a collection of galaxies at the same redshift. + +In a moment, we will see it is integral to the model-fitting API. + +For now, lets use it to create an image of a pair of merging galaxies, noting that a more concise API for creating +the galaxy is used below where the `Sersic` is passed directly to the `Galaxy` object. + +```python +galaxy_1 = ag.Galaxy( + redshift=0.5, + bulge=ag.lp.Sersic( + centre=(0.5, 0.2), intensity=1.0, effective_radius=1.0, sersic_index=2.0 + ), +) + +galaxies = ag.Galaxies( + galaxies=[galaxy, galaxy_1], +) + +aplt.plot_array(array=galaxies.image_2d_from(grid=grid), title="Galaxies Image") +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/4_image_2d.png +:alt: Alternative text +:width: 600 +``` + +## Units + +The units used throughout the galaxy structure literature vary, therefore lets quickly describe the units used in +**PyAutoGalaxy**. + +Most distance quantities, like an `effective_radius` are quantities in terms of angles, which are defined in units +of arc-seconds. To convert these to physical units (e.g. kiloparsecs), we use the redshift of the galaxy and an +input cosmology. A run through of all normal unit conversions is given in guides in the workspace outlined below. + +The use of angles in arc-seconds has an important property, it means that calculations are independent of +the galaxy's redshifts and the input cosmology. This has a number of benefits, for example it makes it straight +forward to compare the properties of different galaxies even when the redshifts of the galaxies are unknown. + +## Extensibility + +All of the objects we've introduced so far are highly extensible, for example a galaxy can be made up of any number of +light profiles and many galaxy objects can be combined into a galaxies object. + +To further illustrate this, we create a merging galaxy system with 4 star forming clumps of light, using a +`SersicSph` profile to make each spherical. + +```python +galaxy_0 = ag.Galaxy( + redshift=0.5, + bulge=ag.lp.Sersic( + centre=(0.0, 0.0), + ell_comps=ag.convert.ell_comps_from(axis_ratio=0.9, angle=45.0), + intensity=0.2, + effective_radius=0.8, + sersic_index=4.0, + ), + disk=ag.lp.Exponential( + centre=(0.0, 0.0), + ell_comps=ag.convert.ell_comps_from(axis_ratio=0.7, angle=30.0), + intensity=0.1, + effective_radius=1.6, + ), + extra_galaxy_0=ag.lp.SersicSph(centre=(1.0, 1.0), intensity=0.5, effective_radius=0.2), + extra_galaxy_1=ag.lp.SersicSph(centre=(0.5, 0.8), intensity=0.5, effective_radius=0.2), + extra_galaxy_2=ag.lp.SersicSph(centre=(-1.0, -0.7), intensity=0.5, effective_radius=0.2), + extra_galaxy_3=ag.lp.SersicSph(centre=(-1.0, 0.4), intensity=0.5, effective_radius=0.2), +) + +galaxy_1 = ag.Galaxy( + redshift=0.5, + bulge=ag.lp.Sersic( + centre=(0.0, 1.0), + ell_comps=(0.0, 0.1), + intensity=0.1, + effective_radius=0.6, + sersic_index=3.0, + ), +) + +galaxies = ag.Galaxies(galaxies=[galaxy_0, galaxy_1]) + +aplt.plot_array(array=galaxies.image_2d_from(grid=grid), title="Galaxies Image") +``` + +The image of the merging galaxy system appears as follows: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_1/5_image_2d.png +:alt: Alternative text +:width: 600 +``` + +## Galaxy Modeling + +Galaxy modeling is the process of fitting a physical model to imaging data in order to infer the structural +and photometric properties of galaxies, such as their light distribution, size, shape, and orientation. + +The primary goal of **PyAutoGalaxy** is to make galaxy modeling **simple, scalable to large datasets, and fast**, +with GPU acceleration provided via JAX. + +The animation below illustrates the galaxy modeling workflow. Many models are fitted to the data iteratively, +progressively improving the quality of the fit until the model closely reproduces the observed image. + +NOTE: Placeholder showing strong lens modeling animation used currently. + +```{image} https://github.com/Jammy2211/auto_files/blob/main/lensmodel.gif?raw=true +:width: 600 +``` + +**Credit: Amy Etherington** + +The next documentation page guides you through galaxy modeling for a variety of data types (e.g. CCD imaging at +different resolutions) and scientific use-cases (e.g. galaxy morphology studies, bulge–disk decomposition). + +## Simulations + +Simulating galaxy images is often essential, for example to: + +- Practice galaxy modeling before working with real data. +- Generate large training sets (e.g. for machine learning). +- Test galaxy formation and structural models in a fully controlled environment. + +The next documentation page guides you through how to simulate galaxies for different types of data +(e.g. CCD imaging) and different modeling goals (e.g. single-component galaxies, multi-component systems). + +## Wrap Up + +This completes the introduction to **PyAutoGalaxy**, including a brief overview of the core API for galaxy +light profile calculations, galaxy modeling, and data simulation. + +Different users will be interested in galaxies across a range of physical scales and scientific applications +(e.g. detailed structural studies, population analyses, or multi-wavelength modeling) and using different +types of data (e.g. CCD imaging or interferometer observations). + +The autogalaxy_workspace repository contains a wide range of examples and tutorials covering these use cases. +The next documentation page helps new users identify the most appropriate starting point based on their +scientific goals. diff --git a/docs/overview/overview_2_new_user_guide.rst b/docs/overview/overview_2_new_user_guide.md similarity index 74% rename from docs/overview/overview_2_new_user_guide.rst rename to docs/overview/overview_2_new_user_guide.md index 759262c82..430d5316e 100644 --- a/docs/overview/overview_2_new_user_guide.rst +++ b/docs/overview/overview_2_new_user_guide.md @@ -1,69 +1,59 @@ -.. _overview_2_new_user_guide: - -New User Guide -============== - -**PyAutoGalaxy** can analyse galaxies for different types of data (e.g. CCD imaging and interferometer observations). -Depending on the data you use, the analysis you perform may differ significantly. - -The autogalaxy_workspace contains a suite of example Jupyter Notebooks, organised by dataset type. To help you find -the most appropriate starting point, answer one simple question: - -What Dataset Type? ------------------- - -You now need to decide what type of data you are interested in: - -- **CDD Imaging**: For image data from telescopes like Hubble and James Webb, go to `imaging/start_here.ipynb `_. - -- **Interferometer**: For radio / sub-mm interferometer from instruments like ALMA, go to `interferometer/start_here.ipynb `_. - -- **Multi-Band Imaging**: For galaxies observed in multiple wavebands go to `multi_band//start_here.ipynb `_. - -Google Colab ------------- - -You can also open and run each notebook directly in Google Colab, which provides a free cloud computing -environment with all the required dependencies already installed. - -This is a great way to get started quickly without needing to install **PyAutoGalaxy** on your own machine, -so you can check it is the right software for you before going through the installation process: - -- `imaging/start_here.ipynb `_: - Galaxy modeling with CCD imaging (e.g. Hubble, James Webb, ground-based telescopes). - -- `interferometer/start_here.ipynb `_: - Galaxy modeling with interferometer data (e.g. ALMA), fitting directly in the uv-plane. - -- `multi_band/start_here.ipynb `_: - Multi-band galaxy modeling to study colour gradients and wavelength-dependent structure. - -Still Unsure? -------------- - -Each notebook is short and self-contained, and can be completed and adapted quickly to your particular task. -Therefore, if you're unsure exactly which scale of lensing applies to you, or quite what data you want to use, you -should just read through a few different notebooks and go from there. - -HowToGalaxy ------------ - -For experienced scientists, the run through above will have been a breeze. Concepts surrounding galaxy structure and -morphology were already familiar and the statistical techniques used for fitting and modeling already understood. - -For those less familiar with these concepts (e.g. undergraduate students, new PhD students or interested members of the -public), things may have been less clear and a slower more detailed explanation of each concept would be beneficial. - -The **HowToGalaxy** Jupyter Notebook lectures provide exactly this. They are a 3+ chapter guide which thoroughly -takes you through the core concepts of galaxy light profiles, teaches you the principles of the statistical -techniques used in modeling and ultimately will allow you to undertake scientific research like a professional astronomer. - -If this sounds like it suits you, checkout the `HowToGalaxy `_ repository now. - -Wrap Up -------- - -After completing this guide, you should be able to use **PyAutoGalaxy** for your science research. - -The biggest decisions you'll need to make are what features and functionality your specific science case requires, -which the next readthedocs page gives an overview of to help you decide. \ No newline at end of file +(overview-2-new-user-guide)= + +# New User Guide + +**PyAutoGalaxy** can analyse galaxies for different types of data (e.g. CCD imaging and interferometer observations). +Depending on the data you use, the analysis you perform may differ significantly. + +The autogalaxy_workspace contains a suite of example Jupyter Notebooks, organised by dataset type. To help you find +the most appropriate starting point, answer one simple question: + +## What Dataset Type? + +You now need to decide what type of data you are interested in: + +- **CDD Imaging**: For image data from telescopes like Hubble and James Webb, go to [imaging/start_here.ipynb](https://github.com/Jammy2211/autogalaxy_workspace/blob/release/notebooks/imaging/start_here.ipynb). +- **Interferometer**: For radio / sub-mm interferometer from instruments like ALMA, go to [interferometer/start_here.ipynb](https://github.com/Jammy2211/autogalaxy_workspace/blob/release/notebooks/interferometer/start_here.ipynb). +- **Multi-Band Imaging**: For galaxies observed in multiple wavebands go to [multi_band//start_here.ipynb](hhttps://github.com/Jammy2211/autogalaxy_workspace/blob/release/notebooks/point_source/start_here.ipynb). + +## Google Colab + +You can also open and run each notebook directly in Google Colab, which provides a free cloud computing +environment with all the required dependencies already installed. + +This is a great way to get started quickly without needing to install **PyAutoGalaxy** on your own machine, +so you can check it is the right software for you before going through the installation process: + +- [imaging/start_here.ipynb](https://colab.research.google.com/github/PyAutoLabs/autogalaxy_workspace/blob/2026.5.1.4/notebooks/imaging/start_here.ipynb): + Galaxy modeling with CCD imaging (e.g. Hubble, James Webb, ground-based telescopes). +- [interferometer/start_here.ipynb](https://colab.research.google.com/github/PyAutoLabs/autogalaxy_workspace/blob/2026.5.1.4/notebooks/interferometer/start_here.ipynb): + Galaxy modeling with interferometer data (e.g. ALMA), fitting directly in the uv-plane. +- [multi_band/start_here.ipynb](https://colab.research.google.com/github/PyAutoLabs/autogalaxy_workspace/blob/2026.5.1.4/notebooks/multi/start_here.ipynb): + Multi-band galaxy modeling to study colour gradients and wavelength-dependent structure. + +## Still Unsure? + +Each notebook is short and self-contained, and can be completed and adapted quickly to your particular task. +Therefore, if you're unsure exactly which scale of lensing applies to you, or quite what data you want to use, you +should just read through a few different notebooks and go from there. + +## HowToGalaxy + +For experienced scientists, the run through above will have been a breeze. Concepts surrounding galaxy structure and +morphology were already familiar and the statistical techniques used for fitting and modeling already understood. + +For those less familiar with these concepts (e.g. undergraduate students, new PhD students or interested members of the +public), things may have been less clear and a slower more detailed explanation of each concept would be beneficial. + +The **HowToGalaxy** Jupyter Notebook lectures provide exactly this. They are a 3+ chapter guide which thoroughly +takes you through the core concepts of galaxy light profiles, teaches you the principles of the statistical +techniques used in modeling and ultimately will allow you to undertake scientific research like a professional astronomer. + +If this sounds like it suits you, checkout the [HowToGalaxy](https://github.com/PyAutoLabs/HowToGalaxy) repository now. + +## Wrap Up + +After completing this guide, you should be able to use **PyAutoGalaxy** for your science research. + +The biggest decisions you'll need to make are what features and functionality your specific science case requires, +which the next readthedocs page gives an overview of to help you decide. diff --git a/docs/overview/overview_3_features.rst b/docs/overview/overview_3_features.md similarity index 69% rename from docs/overview/overview_3_features.rst rename to docs/overview/overview_3_features.md index 2f6192116..5b1d70df8 100644 --- a/docs/overview/overview_3_features.rst +++ b/docs/overview/overview_3_features.md @@ -1,162 +1,159 @@ -.. _overview_3_features: - -Features -======== - -This page provides an overview of the advanced features of **PyAutoGalaxy**. - -Firstly, brief one sentence descriptions of each feature are given, with more detailed descriptions below including -links to the relevant workspace examples. - -**Interferometry**: Modeling of interferometer data (e.g. ALMA, LOFAR) directly in the uv-plane. - -**Multi-Wavelength**: Simultaneous analysis of imaging and / or interferometer datasets observed at different wavelengths. - -**Ellipse Fitting**: Fitting ellipses to determine a galaxy's ellipticity, position angle and centre. - -**Multi Gaussian Expansion (MGE)**: Decomposing a galaxy into hundreds of Gaussians, capturing more complex structures than simple light profiles. - -**Shapelets**: Decomposing a galaxy into a set of shapelet orthogonal basis functions, capturing more complex structures than simple light profiles. - -**Sky Background**: Including the background sky in the model to ensure robust fits to the outskirts of galaxies. - -**Operated Light Profiles**: Assuming a light profile has already been convolved with the PSF, for when the PSF is a significant effect. - -**Pixelizations**: Reconstructing a galaxy's on a mesh of pixels, to capture extremely irregular structures like spiral arms. - -Interferometry --------------- - -Modeling interferometer data from submillimeter (e.g. ALMA) and radio (e.g. LOFAR) observatories: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/paper/almacombined.png - :width: 600 - :alt: Alternative text - -Visibilities data is fitted directly in the uv-plane, circumventing issues that arise when fitting a dirty image -such as correlated noise. This uses the non-uniform fast fourier transform algorithm -[PyNUFFT](https://github.com/jyhmiinlin/pynufft) to efficiently map the galaxy model images to the uv-plane. - -Checkout the ``autogalaxy_workspace/*/interferometer`` package to get started. - -Multi-Wavelength ----------------- - -Modeling imaging datasets observed at different wavelengths (e.g. HST F814W and F150W) simultaneously or simultaneously -analysing imaging and interferometer data: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_3/g_image.png - :width: 400 - :alt: Alternative text - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_3/r_image.png - :width: 400 - :alt: Alternative text - -The appearance of the galaxy changes as a function of wavelength, therefore multi-wavelength analysis means we can learn -more about the different components in a galaxy (e.g a redder bulge and bluer disk) or when imaging and interferometer -data are combined, we can compare the emission from stars and dust. - -Checkout the ``autogalaxy_workspace/*/multi`` package to get started, however combining datasets is a more advanced -feature and it is recommended you first get to grips with the core API. - -Ellipse Fitting ---------------- - -Ellipse fitting is a technique which fits many ellipses to a galaxy's emission to determine its ellipticity, position -angle and centre, without assuming a parametric form for its light (e.g. a Sersic profile): - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_3/ellipse.png - :width: 600 - :alt: Alternative text - -This provides complementary information to parametric light profile fitting, for example giving insights on whether -the ellipticity and position angle are constant with radius or if the galaxy's emission is lopsided. - -There are also multipole moment extensions to ellipse fitting, which determine higher order deviations from elliptical -symmetry providing even more information on the galaxy's structure. - -The following paper describes the technique in detail: https://arxiv.org/html/2407.12983v1 - -Checkout ``autogalaxy_workspace/notebooks/features/ellipse_fitting.ipynb`` to learn how to use ellipse fitting. - -Multi Gaussian Expansion (MGE) ------------------------------- - -An MGE decomposes the light of a galaxy into tens or hundreds of two dimensional Gaussians: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_3/mge.png - :width: 600 - :alt: Alternative text - -In the image above, 30 Gaussians are shown, where their sizes go from below the pixel scale (in order to resolve -point emission) to beyond the size of the galaxy (to capture its extended emission). - -Scientific Applications include capturing departures from elliptical symmetry in the light of galaxies, providing a -flexible model to deblend the emission of point sources (e.g. quasars) from the emission of their host galaxy and -deprojecting the light of a galaxy from 2D to 3D. - -Checkout ``autogalaxy_workspace/notebooks/features/multi_gaussian_expansion.ipynb`` to learn how to use an MGE. - -Shapelets ---------- - -Shapelets are a set of orthogonal basis functions that can be combined the represent galaxy structures: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/shapelets.png - :width: 600 - :alt: Alternative text - -Scientific Applications include capturing symmetric structures in a galaxy which are more complex than a Sersic profile, -irregular and asymmetric structures in a galaxy like spiral arms and providing a flexible model to deblend the emission -of point sources (e.g. quasars) from the emission of their host galaxy. - -Checkout ``autogalaxy_workspace/notebooks/features/shapelets.ipynb`` to learn how to use shapelets. - -Sky Background --------------- - -When an image of a galaxy is observed, the background sky contributes light to the image and adds noise: - -For detailed studies of the outskirts of galaxies (e.g. stellar halos, faint extended disks), the sky background must be -accounted for in the model to ensure robust and accurate fits. - -Checkout ``autogalaxy_workspace/notebooks/features/sky_background.ipynb`` to learn how to use include the sky -background in your model. - -Operated Light Profiles ------------------------ - -An operated light profile is one where it is assumed to already be convolved with the PSF of the data, with the -``Moffat`` and ``Gaussian`` profiles common choices: - -They are used for certain scientific applications where the PSF convolution is known to be a significant effect and -the knowledge of the PSF allows for detailed modeling abd deblending of the galaxy's light. - -Checkout ``autogalaxy_workspace/notebooks/features/operated_light_profiles.ipynb`` to learn how to use operated profiles. - -Pixelizations -------------- - -A pixelization reconstructs a galaxy's light on a mesh of pixels, for example a rectangular mesh, Delaunay -triangulation or Voronoi grid. - -These models are highly flexible and can capture complex structures in a galaxy's light that parametric models -like a Sersic profile cannot, for example spiral arms or asymmetric merging features. - -The image below shows a non parametric of a galaxy observed in the Hubble Ultra Deep Field. Its bulge and disk are -fitted accurately using light profiles, whereas its asymmetric and irregular spiral arm features are accurately -captured using a rectangular mesh: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/paper/hstcombined.png - :width: 600 - :alt: Alternative text - -Checkout ``autogalaxy_workspace/notebooks/features/pixelizations.ipynb`` to learn how to use a pixelization, however -this is a more advanced feature and it is recommended you first get to grips with the core API. - -Other ------ - -- Automated pipelines / database tools. -- Graphical models. \ No newline at end of file +(overview-3-features)= + +# Features + +This page provides an overview of the advanced features of **PyAutoGalaxy**. + +Firstly, brief one sentence descriptions of each feature are given, with more detailed descriptions below including +links to the relevant workspace examples. + +**Interferometry**: Modeling of interferometer data (e.g. ALMA, LOFAR) directly in the uv-plane. + +**Multi-Wavelength**: Simultaneous analysis of imaging and / or interferometer datasets observed at different wavelengths. + +**Ellipse Fitting**: Fitting ellipses to determine a galaxy's ellipticity, position angle and centre. + +**Multi Gaussian Expansion (MGE)**: Decomposing a galaxy into hundreds of Gaussians, capturing more complex structures than simple light profiles. + +**Shapelets**: Decomposing a galaxy into a set of shapelet orthogonal basis functions, capturing more complex structures than simple light profiles. + +**Sky Background**: Including the background sky in the model to ensure robust fits to the outskirts of galaxies. + +**Operated Light Profiles**: Assuming a light profile has already been convolved with the PSF, for when the PSF is a significant effect. + +**Pixelizations**: Reconstructing a galaxy's on a mesh of pixels, to capture extremely irregular structures like spiral arms. + +## Interferometry + +Modeling interferometer data from submillimeter (e.g. ALMA) and radio (e.g. LOFAR) observatories: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/paper/almacombined.png +:alt: Alternative text +:width: 600 +``` + +Visibilities data is fitted directly in the uv-plane, circumventing issues that arise when fitting a dirty image +such as correlated noise. This uses the non-uniform fast fourier transform algorithm +\[PyNUFFT\]() to efficiently map the galaxy model images to the uv-plane. + +Checkout the `autogalaxy_workspace/*/interferometer` package to get started. + +## Multi-Wavelength + +Modeling imaging datasets observed at different wavelengths (e.g. HST F814W and F150W) simultaneously or simultaneously +analysing imaging and interferometer data: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_3/g_image.png +:alt: Alternative text +:width: 400 +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_3/r_image.png +:alt: Alternative text +:width: 400 +``` + +The appearance of the galaxy changes as a function of wavelength, therefore multi-wavelength analysis means we can learn +more about the different components in a galaxy (e.g a redder bulge and bluer disk) or when imaging and interferometer +data are combined, we can compare the emission from stars and dust. + +Checkout the `autogalaxy_workspace/*/multi` package to get started, however combining datasets is a more advanced +feature and it is recommended you first get to grips with the core API. + +## Ellipse Fitting + +Ellipse fitting is a technique which fits many ellipses to a galaxy's emission to determine its ellipticity, position +angle and centre, without assuming a parametric form for its light (e.g. a Sersic profile): + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_3/ellipse.png +:alt: Alternative text +:width: 600 +``` + +This provides complementary information to parametric light profile fitting, for example giving insights on whether +the ellipticity and position angle are constant with radius or if the galaxy's emission is lopsided. + +There are also multipole moment extensions to ellipse fitting, which determine higher order deviations from elliptical +symmetry providing even more information on the galaxy's structure. + +The following paper describes the technique in detail: + +Checkout `autogalaxy_workspace/notebooks/features/ellipse_fitting.ipynb` to learn how to use ellipse fitting. + +## Multi Gaussian Expansion (MGE) + +An MGE decomposes the light of a galaxy into tens or hundreds of two dimensional Gaussians: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/docs/overview/images/overview_3/mge.png +:alt: Alternative text +:width: 600 +``` + +In the image above, 30 Gaussians are shown, where their sizes go from below the pixel scale (in order to resolve +point emission) to beyond the size of the galaxy (to capture its extended emission). + +Scientific Applications include capturing departures from elliptical symmetry in the light of galaxies, providing a +flexible model to deblend the emission of point sources (e.g. quasars) from the emission of their host galaxy and +deprojecting the light of a galaxy from 2D to 3D. + +Checkout `autogalaxy_workspace/notebooks/features/multi_gaussian_expansion.ipynb` to learn how to use an MGE. + +## Shapelets + +Shapelets are a set of orthogonal basis functions that can be combined the represent galaxy structures: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/shapelets.png +:alt: Alternative text +:width: 600 +``` + +Scientific Applications include capturing symmetric structures in a galaxy which are more complex than a Sersic profile, +irregular and asymmetric structures in a galaxy like spiral arms and providing a flexible model to deblend the emission +of point sources (e.g. quasars) from the emission of their host galaxy. + +Checkout `autogalaxy_workspace/notebooks/features/shapelets.ipynb` to learn how to use shapelets. + +## Sky Background + +When an image of a galaxy is observed, the background sky contributes light to the image and adds noise: + +For detailed studies of the outskirts of galaxies (e.g. stellar halos, faint extended disks), the sky background must be +accounted for in the model to ensure robust and accurate fits. + +Checkout `autogalaxy_workspace/notebooks/features/sky_background.ipynb` to learn how to use include the sky +background in your model. + +## Operated Light Profiles + +An operated light profile is one where it is assumed to already be convolved with the PSF of the data, with the +`Moffat` and `Gaussian` profiles common choices: + +They are used for certain scientific applications where the PSF convolution is known to be a significant effect and +the knowledge of the PSF allows for detailed modeling abd deblending of the galaxy's light. + +Checkout `autogalaxy_workspace/notebooks/features/operated_light_profiles.ipynb` to learn how to use operated profiles. + +## Pixelizations + +A pixelization reconstructs a galaxy's light on a mesh of pixels, for example a rectangular mesh, Delaunay +triangulation or Voronoi grid. + +These models are highly flexible and can capture complex structures in a galaxy's light that parametric models +like a Sersic profile cannot, for example spiral arms or asymmetric merging features. + +The image below shows a non parametric of a galaxy observed in the Hubble Ultra Deep Field. Its bulge and disk are +fitted accurately using light profiles, whereas its asymmetric and irregular spiral arm features are accurately +captured using a rectangular mesh: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/paper/hstcombined.png +:alt: Alternative text +:width: 600 +``` + +Checkout `autogalaxy_workspace/notebooks/features/pixelizations.ipynb` to learn how to use a pixelization, however +this is a more advanced feature and it is recommended you first get to grips with the core API. + +## Other + +- Automated pipelines / database tools. +- Graphical models.