.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/basics/demo_quickstart.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        New to DeepInverse? Get started with the basics with the
        :ref:`5 minute quickstart tutorial <sphx_glr_auto_examples_basics_demo_quickstart.py>`.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_basics_demo_quickstart.py:


5 minute quickstart tutorial
============================

Follow this example to get started with DeepInverse in under 5 minutes.

**Contents**

1. `Install <#install>`__
2. `Physics <#physics>`__
3. `Models <#models>`__
4. `Datasets <#datasets>`__
5. `What's next <#what-s-next>`__

.. GENERATED FROM PYTHON SOURCE LINES 18-29

1. Install
~~~~~~~~~~

First, install and import the latest stable release of `deepinv`:

.. code:: bash

   pip install deepinv

We then get the device (CPU in the case of this example).


.. GENERATED FROM PYTHON SOURCE LINES 29-35

.. code-block:: Python


    import deepinv as dinv
    import torch

    device = dinv.utils.get_freer_gpu() if torch.cuda.is_available() else "cpu"








.. GENERATED FROM PYTHON SOURCE LINES 36-39

2. Physics
~~~~~~~~~~


.. GENERATED FROM PYTHON SOURCE LINES 42-44

In DeepInverse, `x` are images:


.. GENERATED FROM PYTHON SOURCE LINES 44-47

.. code-block:: Python


    x = dinv.utils.load_example("butterfly.png", device=device)








.. GENERATED FROM PYTHON SOURCE LINES 48-49

Images are tensors of shape `B, C, ...` where `B` is batch size, `C` are channels and `...` are spatial dimensions:

.. GENERATED FROM PYTHON SOURCE LINES 49-52

.. code-block:: Python


    print(x.shape)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    torch.Size([1, 3, 256, 256])




.. GENERATED FROM PYTHON SOURCE LINES 53-56

:ref:`Imaging forward operators <physics_intro>` are called `physics` and simulate
measurements `y` from `x`.


.. GENERATED FROM PYTHON SOURCE LINES 56-62

.. code-block:: Python


    physics = dinv.physics.Inpainting(x.shape[1:], mask=0.3, device=device)

    y = physics(x)









.. GENERATED FROM PYTHON SOURCE LINES 63-66

DeepInverse implements
:ref:`many different types of physics <physics>` across various imaging modalities.
Physics also possess noise models such as Gaussian or Poisson noise.

.. GENERATED FROM PYTHON SOURCE LINES 66-74

.. code-block:: Python


    physics.noise_model = dinv.physics.GaussianNoise(sigma=0.1)

    y = physics(x)

    dinv.utils.plot({"GT": x, "Noisy inpainting measurement": y})





.. image-sg:: /auto_examples/basics/images/sphx_glr_demo_quickstart_001.png
   :alt: GT, Noisy inpainting measurement
   :srcset: /auto_examples/basics/images/sphx_glr_demo_quickstart_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 75-77

Many physics also take
:ref:`physics parameters <parameter-dependent-operators>` such as `mask`, `filter`, `sigma` etc.:

.. GENERATED FROM PYTHON SOURCE LINES 77-86

.. code-block:: Python


    # Blur with Gaussian filter parameter
    filter = dinv.physics.blur.gaussian_blur((5, 5))

    physics = dinv.physics.BlurFFT(x.shape[1:], filter=filter, device=device)

    # Simulate measurements
    y = physics(x)








.. GENERATED FROM PYTHON SOURCE LINES 87-89

You can easily use your own params by passing these into the `physics`,
or you can use a `generator` to :ref:`generate random params <physics_generators>`:

.. GENERATED FROM PYTHON SOURCE LINES 89-111

.. code-block:: Python


    # Blur kernel random generator
    physics_generator = dinv.physics.generator.MotionBlurGenerator(
        psf_size=(31, 31), num_channels=3, device=device
    )

    # Generate a dict of random params {"filter": ...}
    params = physics_generator.step()

    # Update physics during forward call
    y2 = physics(x, **params)

    dinv.utils.plot(
        {
            "GT": x,
            "Blurred...": y,
            "... with Gaussian kernel": filter,
            "Blurred ...": y2,
            "...with motion kernel": params["filter"],
        }
    )




.. image-sg:: /auto_examples/basics/images/sphx_glr_demo_quickstart_002.png
   :alt: GT, Blurred..., ... with Gaussian kernel, Blurred ..., ...with motion kernel
   :srcset: /auto_examples/basics/images/sphx_glr_demo_quickstart_002.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 112-115

Physics are powerful objects and :ref:`have many methods <physics_intro>`, for example a
pseudo-inverse:


.. GENERATED FROM PYTHON SOURCE LINES 115-121

.. code-block:: Python


    # You can also update params like so
    physics.update(filter=filter.to(device))

    x_pinv = physics.A_dagger(y)








.. GENERATED FROM PYTHON SOURCE LINES 122-124

As it is well-known in the field of inverse problems, the pseudo-inverse can give good results
if the problem is noiseless, but it completely fails in the presence of noise - this is why we need reconstructors!

.. GENERATED FROM PYTHON SOURCE LINES 124-134

.. code-block:: Python


    physics.noise_model = dinv.physics.GaussianNoise(sigma=0.1)

    y = physics(x)

    x_pinv_noise = physics.A_dagger(y)

    dinv.utils.plot({"Pseudoinv w/o noise": x_pinv, "Pseudoinv with noise": x_pinv_noise})





.. image-sg:: /auto_examples/basics/images/sphx_glr_demo_quickstart_003.png
   :alt: Pseudoinv w/o noise, Pseudoinv with noise
   :srcset: /auto_examples/basics/images/sphx_glr_demo_quickstart_003.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 135-139

.. tip::

   Want to use DeepInverse with your own physics operator? Check out :ref:`sphx_glr_auto_examples_basics_demo_custom_physics.py` for a tutorial!


.. GENERATED FROM PYTHON SOURCE LINES 142-152

3. Models
~~~~~~~~~

In DeepInverse, a `model` is a reconstruction algorithm that
**reconstructs** images from `y` and knowledge of `physics`.

.. tip::
    Many models, such as :class:`Reconstruct Anything Model <deepinv.models.RAM>`, are :ref:`pretrained reconstructors <pretrained-models>` and can
    be used out of the box. See :ref:`sphx_glr_auto_examples_basics_demo_pretrained_model.py` for a full example.


.. GENERATED FROM PYTHON SOURCE LINES 152-157

.. code-block:: Python


    model = dinv.models.RAM(pretrained=True, device=device)

    x_hat = model(y, physics)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Downloading: "https://huggingface.co/mterris/ram/resolve/main/ram.pth.tar" to /home/runner/.cache/torch/hub/checkpoints/ram.pth.tar

      0%|          | 0.00/136M [00:00<?, ?B/s]
      2%|▏         | 2.75M/136M [00:00<00:05, 23.5MB/s]
      4%|▎         | 5.00M/136M [00:00<00:10, 13.2MB/s]
      5%|▍         | 6.50M/136M [00:00<00:12, 10.7MB/s]
      6%|▌         | 8.12M/136M [00:00<00:10, 12.3MB/s]
     27%|██▋       | 36.2M/136M [00:00<00:01, 86.1MB/s]
     44%|████▍     | 60.4M/136M [00:00<00:00, 131MB/s] 
     67%|██████▋   | 91.9M/136M [00:00<00:00, 187MB/s]
     88%|████████▊ | 119M/136M [00:01<00:00, 214MB/s] 
    100%|██████████| 136M/136M [00:01<00:00, 125MB/s]




.. GENERATED FROM PYTHON SOURCE LINES 158-161

Plot the image `x`, the measurement `y` and the reconstructed image
`x_hat` and compute :ref:`metrics <metric>`:


.. GENERATED FROM PYTHON SOURCE LINES 161-175

.. code-block:: Python


    metric = dinv.metric.PSNR()

    psnr_y = metric(y, x).item()
    psnr_x_hat = metric(x_hat, x).item()

    dinv.utils.plot(
        {
            f"Measurement\n {psnr_y:.2f} dB": y,
            f"Reconstruction\n {psnr_x_hat:.2f} dB": x_hat,
            "GT": x,
        }
    )




.. image-sg:: /auto_examples/basics/images/sphx_glr_demo_quickstart_004.png
   :alt: Measurement  14.19 dB, Reconstruction  19.22 dB, GT
   :srcset: /auto_examples/basics/images/sphx_glr_demo_quickstart_004.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 176-180

Some models are only :ref:`denoisers <denoisers>` that **denoise**
images from `y` and `sigma`, which can be used to build many
:ref:`model-based reconstruction algorithms <iterative>`.


.. GENERATED FROM PYTHON SOURCE LINES 180-193

.. code-block:: Python


    denoiser = dinv.models.DRUNet(device=device)

    x_denoised = denoiser(y, sigma=0.1)

    model = dinv.optim.DPIR(sigma=0.1, denoiser=denoiser, device=device)

    x_hat = model(y, physics)

    dinv.utils.plot(
        {"Measurement": y, "Denoised": x_denoised, "Reconstructed": x_hat, "GT": x}
    )




.. image-sg:: /auto_examples/basics/images/sphx_glr_demo_quickstart_005.png
   :alt: Measurement, Denoised, Reconstructed, GT
   :srcset: /auto_examples/basics/images/sphx_glr_demo_quickstart_005.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Downloading: "https://huggingface.co/deepinv/drunet/resolve/main/drunet_deepinv_color_finetune_22k.pth?download=true" to /home/runner/.cache/torch/hub/checkpoints/drunet_deepinv_color_finetune_22k.pth

      0%|          | 0.00/125M [00:00<?, ?B/s]
     10%|▉         | 12.4M/125M [00:00<00:00, 129MB/s]
     32%|███▏      | 39.2M/125M [00:00<00:00, 218MB/s]
     53%|█████▎    | 66.1M/125M [00:00<00:00, 247MB/s]
     76%|███████▌  | 94.4M/125M [00:00<00:00, 266MB/s]
     99%|█████████▉| 124M/125M [00:00<00:00, 281MB/s] 
    100%|██████████| 125M/125M [00:00<00:00, 259MB/s]




.. GENERATED FROM PYTHON SOURCE LINES 194-199

DeepInverse covers
:ref:`many frameworks of reconstruction algorithms <reconstructors>`
including :ref:`deep model architectures <deep-reconstructors>`, :ref:`iterative algorithms <iterative>`, :ref:`sampling algorithms <sampling>`
(e.g. diffusion models), and :ref:`unfolded models <unfolded>`.


.. GENERATED FROM PYTHON SOURCE LINES 199-203

.. code-block:: Python


    # Reconstruct Anything Model foundation model
    model = dinv.models.RAM(pretrained=True, device=device)








.. GENERATED FROM PYTHON SOURCE LINES 204-208

.. tip::

   Want to use DeepInverse with your own network? Just inherit from the reconstructor base class :class:`deepinv.models.Reconstructor`!


.. GENERATED FROM PYTHON SOURCE LINES 211-222

4. Datasets
~~~~~~~~~~~

You can use DeepInverse with :ref:`dataset <datasets>`, for testing or training. First,
define a ground-truth dataset. We implement wrappers for
:ref:`many popular imaging datasets <datasets>` across domains including natural images,
medical imaging, satellite imaging, etc.

.. tip::
    It's easy to use your own dataset with DeepInverse. See :ref:`sphx_glr_auto_examples_basics_demo_custom_dataset.py` for a tutorial.


.. GENERATED FROM PYTHON SOURCE LINES 222-228

.. code-block:: Python


    dataset = dinv.datasets.SimpleFastMRISliceDataset(
        "data", anatomy="brain", download=True
    )






.. rst-class:: sphx-glr-script-out

 .. code-block:: none


      0%|          | 0/820534 [00:00<?, ?it/s]
    100%|██████████| 801k/801k [00:00<00:00, 18.6MB/s]




.. GENERATED FROM PYTHON SOURCE LINES 229-233

:ref:`Datasets <datasets>` return either `x`, tuples `x, y` or `x, y, params` of images,
measurements, and optional physics parameters. Given a ground-truth
dataset, you can simulate a dataset with random physics:


.. GENERATED FROM PYTHON SOURCE LINES 233-251

.. code-block:: Python


    physics = dinv.physics.MRI(device=device)

    physics_generator = dinv.physics.generator.RandomMaskGenerator(
        (320, 320), device=device
    )

    path = dinv.datasets.generate_dataset(
        dataset,
        physics,
        save_dir="data",
        physics_generator=physics_generator,
        device=device,
    )

    dataset = dinv.datasets.HDF5Dataset(path, load_physics_generator_params=True)






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Dataset has been saved at data/dinv_dataset0.h5




.. GENERATED FROM PYTHON SOURCE LINES 252-254

You can use this dataset to :ref:`test or train <trainer>` a model:


.. GENERATED FROM PYTHON SOURCE LINES 254-266

.. code-block:: Python


    import torch

    dinv.test(
        model,
        torch.utils.data.DataLoader(dataset),
        physics,
        plot_images=True,
        device=device,
    )





.. image-sg:: /auto_examples/basics/images/sphx_glr_demo_quickstart_006.png
   :alt: Ground truth, Measurement, No learning, Reconstruction
   :srcset: /auto_examples/basics/images/sphx_glr_demo_quickstart_006.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


      0%|                                                                                                                           | 0/2 [00:00<?, ?it/s]
    Test:   0%|                                                                                                                     | 0/2 [00:00<?, ?it/s]
    Test:   0%|                                                                                   | 0/2 [00:04<?, ?it/s, PSNR=41.4, PSNR no learning=31.4]
    Test:  50%|█████████████████████████████████████▌                                     | 1/2 [00:04<00:04,  4.43s/it, PSNR=41.4, PSNR no learning=31.4]
    Test:  50%|█████████████████████████████████████▌                                     | 1/2 [00:04<00:04,  4.43s/it, PSNR=41.4, PSNR no learning=31.4]
    Test:  50%|█████████████████████████████████████▌                                     | 1/2 [00:08<00:04,  4.43s/it, PSNR=40.2, PSNR no learning=30.5]
    Test: 100%|███████████████████████████████████████████████████████████████████████████| 2/2 [00:08<00:00,  4.43s/it, PSNR=40.2, PSNR no learning=30.5]
    Test: 100%|███████████████████████████████████████████████████████████████████████████| 2/2 [00:08<00:00,  4.43s/it, PSNR=40.2, PSNR no learning=30.5]
    Test results:
    PSNR no learning: 30.459 +- 0.940
    PSNR: 40.170 +- 1.241

    {'PSNR no learning': np.float64(30.458812713623047), 'PSNR no learning_std': np.float64(0.939930729178376), 'PSNR': np.float64(40.16980743408203), 'PSNR_std': np.float64(1.2413168748421881)}



.. GENERATED FROM PYTHON SOURCE LINES 267-271

.. tip::

   Want to use DeepInverse with your own dataset? Check out :ref:`sphx_glr_auto_examples_basics_demo_custom_dataset.py` for a tutorial!


.. GENERATED FROM PYTHON SOURCE LINES 274-292

🎉 Well done, you now know how to use DeepInverse!

What's next?
~~~~~~~~~~~~

-  Try more basic examples, including
   :ref:`how to inference a pretrained model <sphx_glr_auto_examples_basics_demo_pretrained_model.py>`,
   :ref:`how to use your own dataset <sphx_glr_auto_examples_basics_demo_custom_dataset.py>`, or
   :ref:`how to use your custom physics operator <sphx_glr_auto_examples_basics_demo_custom_physics.py>`.
-  Dive deeper into our full library of examples.
-  Read the :ref:`User Guide <user_guide>` for further details on the
   concepts introduced here.
-  Want help?
   `Open an issue <https://github.com/deepinv/deepinv/issues>`_ ask
   a message on our `Discord <https://discord.gg/qBqY5jKw3p>`_ or
   get in touch with our
   `MAINTAINERS <https://github.com/deepinv/deepinv/blob/main/MAINTAINERS.md>`_.



.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 31.913 seconds)


.. _sphx_glr_download_auto_examples_basics_demo_quickstart.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: demo_quickstart.ipynb <demo_quickstart.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: demo_quickstart.py <demo_quickstart.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: demo_quickstart.zip <demo_quickstart.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_