diff --git a/docs/_img/tikz/block_diagram.tex b/docs/_img/tikz/block_diagram.tex deleted file mode 100644 index 3dbb9ce..0000000 --- a/docs/_img/tikz/block_diagram.tex +++ /dev/null @@ -1,34 +0,0 @@ -\documentclass{standalone} -\usepackage{tikz} - - -\usetikzlibrary{positioning,shapes,arrows} - -\begin{document} -\tikzstyle{class}=[rectangle, thick, draw=black, minimum width=3cm, - minimum height=1cm] -\tikzstyle{myarrow}=[->, >=open triangle 90, thick] -\tikzstyle{line}=[-, thick] - -\begin{tikzpicture}[node distance=1cm] - - \node (Telescope) [class] {\verb`Telescope`}; - \node (Instrument) [class, below=of Telescope] {\verb`Instrument`}; - - \node (AuxNode01) [text width=1cm, below=of Instrument] {}; - \node (AuxNode02) [text width=2cm, below=of AuxNode01] {}; - - \node (OpticalSystem) [class, left=of AuxNode02] {\verb`OpticalSystem`}; - \node (Detector) [class, right=of AuxNode02] {\verb`Detector`}; - - \node (Element) [class, below=of OpticalSystem] {\verb`Element`}; - - \draw[myarrow] (Instrument.north) -- (Telescope.south); - - \draw[myarrow] (OpticalSystem.north) -- ++(0,0.4) -| (Instrument.south); - \draw[line] (OpticalSystem.north) -- ++(0,0.4) -| (Detector.north); - - \draw[myarrow] (Element.north) -- (OpticalSystem.south); - -\end{tikzpicture} -\end{document} diff --git a/docs/examples/general/attributes.rst b/docs/examples/general/attributes.rst deleted file mode 100644 index 192bac9..0000000 --- a/docs/examples/general/attributes.rst +++ /dev/null @@ -1,103 +0,0 @@ -System Attributes and Common Data -================================= - -Defining system attributes --------------------------- -System attributes should be defined as constants in whichever module makes the most -sense. When other modules require access to an attribute, it should be imported from the -module in which it is defined. In this way, attributes can be used throughout the model -but only need to be changed/updated in one place. For example: - -.. code:: python3 - - import lentil - - FOCAL_LENGTH = 3 - - class TinyPupil(lentil.Pupil): - def __init__(self): - super().__init__(focal_length=FOCAL_LENGTH) - - -Loading Numpy ``.npy`` and ``.npz`` files ------------------------------------------ -Numpy data stored in ``.npy`` and ``.npz`` files should be loaded with the -`numpy.load `_ -command. - -* ``.npy`` files store single arrays -* ``.npz`` files store multiple arrays in a dictionary-like mapping - -We'll update the example above to load in some additional Numpy data: - - -.. code:: python3 - - import numpy as np - import lentil - - FOCAL_LENGTH = 3 - - AMPLITUDE = np.load('amp.npy') - with np.load('mask.npz') as data: - MASK = data['mask'] - - pupil = lentil.Pupil(focal_length=FOCAL_LENGTH, - mask=MASK, - amplitude=AMPLITUDE) - - -Loading ``FITS`` files ----------------------- -FITS files are most easily loaded using Astropy. You'll have to figure out which Header -Data Unit (HDU) stores the data you need, but the interface is otherwise fairly -straightforward: - -.. code:: python3 - - from astropy.io import fits - - hdul = fits.open('opd.fits') - OPD = hdul[0].data - - -More details are available in the `astropy.io.fits `_ -documentation. - -Loading MATLAB ``.MAT`` files ------------------------------ -For v6 and v7 to v7.2 MAT files, scipy.io.loadmat does the trick. MATLAB 7.3 format MAT -files are HDF5 and not supported by scipy.io.loadmat but can probably be loaded by some -other HDF5 Python library. - -.. code:: python3 - - from scipy.io import loadmat - - mat_contents = loadmat('opd.mat') - OPD = mat_contents('opd') - - -More details are available in the `scipy.io.loadmat `_ -documentation. - -.. note:: - - The easiest way to deal with MAT files is to convert them to Numpy arrays with - `mat2ndarray `_, - get them in to Python, and save them using numpy.save. - - -Loading ``CSV`` files ---------------------- - -.. code:: python3 - - import numpy as np - - OPD = np.genfromtxt('opd.csv', delimiter=',', ship_header=1) - -More details are available in the `numpy.genfromtxt `_ -documenation. - - diff --git a/docs/examples/general/large.rst b/docs/examples/general/large.rst deleted file mode 100644 index 68a44a4..0000000 --- a/docs/examples/general/large.rst +++ /dev/null @@ -1,86 +0,0 @@ -Larger Models -============= -A simple Lentil model can be written in a single file but as the model grows, -maintaining all the code in a single file becomes more difficult. It usually makes more -sense to divide the code into several smaller *modules* and interact with the modules -via a single *package*. The model package should be divided into modules in some logical -way. One way to separate the code is: - -* A top-level module containing the main model and providing linkage between the - individual components (primarily the optical model, radiometric model, and detector - model -* An module that defines the model's optical planes -* A module defining the model's radiometric properties (if this is very simple, it can - be included in the top-level or planes module) -* A module for the detector. If a model needs to represent multiple detectors, they - can be grouped in a single ``detector.py`` module, or be broken out into individual - modules. -* A ``data`` subdirectory for holding static data. This subdirectory can be further - subdivided as needed for easier organization. -* Top-level subdirectories for documentation and tests -* A top-level ``scripts`` subdirectory can be useful for holding commonly used scripts - for interacting with the model - -A fairly standard directory structure might look something like this: - -.. code-block:: none - - ~/dev/tiny-lentil - ├── tiny_telescope/ - │ ├── __init__.py - │ ├── detector.py - │ ├── tiny.py - │ ├── planes.py - │ ├── radiometry.py - │ └── data/ - │ ├── detector_qe.csv - │ ├── pupil_mask.npy - │ └── sensitivities.npz - ├── docs/ - ├── scripts/ - ├── tests/ - ├── .gitignore - ├── README.md - └── setup.py - -If the ``tiny.py`` module contains the top level object called ``TinyTelescope``, the -``__init__.py`` should look like this: - -.. code-block:: python3 - - from tiny_telescope.tiny import TinyTelescope - -With a model defined in this way, users can interact with it in a standard way: - -.. code-block:: python3 - - >>> from tiny_telescope import TinyTelescope - >>> t = TinyTelescope() - -**setyp.py** - -.. code-block:: python3 - - import os - from setuptools import setup - - setup( - name='tiny-monocle', - version='1.0.0', - author='Tim Apple', - author_email='tim@apple.com', - packages=['tiny_telescope'], - package_data={'tiny_telescope': ['data/*']}, - install_requires=['lentil>=0.1'], - python_requires='>=3.7', - ) - -**.gitignore** - -.. code-block:: none - - __pycache__/ - *.pyc - *.m~ - .DS_Store - *.swp diff --git a/docs/examples/general/simple.rst b/docs/examples/general/simple.rst deleted file mode 100644 index 7599c79..0000000 --- a/docs/examples/general/simple.rst +++ /dev/null @@ -1,66 +0,0 @@ -Simple Models -============= -All but the simplest models will benefit from being developed in Python modules. Simple -models not requiring extensive custom code development can often be written in a single -module. - -A simple model may have a directory structure that looks something like this: - -.. code-block:: none - - ~/dev/tiny-lentil - ├── tiny_telescope/ - │ ├── __init__.py - │ ├── tiny.py - │ ├── detector_qe.csv - │ ├── pupil_mask.npy - │ └── sensitivities.npz - ├── .gitignore - ├── README.md - └── setup.py - -* The ``tiny.py`` module should contain all of the code needed to represent model - behaviors -* Additional static files are included as needed - -If the ``tiny.py`` module contains the top level object called ``TinyTelescope``, the -``__init__.py`` should look like this: - -.. code-block:: python3 - - from tiny_telescope.tiny import TinyTelescope - -With a model defined in this way, users can interact with it in a standard way: - -.. code-block:: python3 - - >>> from tiny_telescope import TinyTelescope - >>> t = TinyTelescope() - -**setyp.py** - -.. code-block:: python3 - - import os - from setuptools import setup - - setup( - name='tiny-lentil', - version='1.0.0', - author='Tim Apple', - author_email='tim@apple.com', - packages=['tiny_telescope'], - package_data={'tiny_telescope': ['data/*']}, - install_requires=['lentil>=0.1'], - python_requires='>=3.7', - ) - -**.gitignore** - -.. code-block:: none - - __pycache__/ - *.pyc - *.m~ - .DS_Store - *.swp diff --git a/docs/examples/index.rst b/docs/examples/index.rst index cdd1421..c9cfa44 100644 --- a/docs/examples/index.rst +++ b/docs/examples/index.rst @@ -6,6 +6,8 @@ Examples This page contains examples and useful model design patterns. +.. _examples.end_to_end: + End-to-end simulations ====================== @@ -16,61 +18,64 @@ End-to-end simulations :link-type: doc :margin: 2 2 0 0 - A simple diffraction simulation + .. image:: /_static/img/psf.png + :width: 175px + :align: center + + Simple diffraction simulation - .. grid-item-card:: Title 2 + .. grid-item-card:: :margin: 2 2 0 0 - B + Broadband diffraction simulation - .. grid-item-card:: Title 3 + .. grid-item-card:: :margin: 2 2 0 0 - C + Segmented aperture diffraction simulation - .. grid-item-card:: Title 4 + .. grid-item-card:: :margin: 2 2 0 0 - D + Diffraction simulation with large tilt + .. grid-item-card:: + :margin: 2 2 0 0 -.. toctree:: - :caption: End-to-end simulations - :hidden: + Radiometrically correct propagation - simple - general/simple - general/large - general/attributes + .. grid-item-card:: + :margin: 2 2 0 0 -.. toctree:: - :caption: Model patterns - :hidden: + Including a detector model - planes/filter_wheel - planes/rb_element - planes/translation_stage .. toctree:: - :caption: MATLAB + :caption: End-to-end simulations :hidden: - matlab/matlab_interface + simple + + +.. _examples.useful_patterns: -.. _patterns.planes: +Useful patterns +=============== -Planes -====== .. toctree:: - :caption: Planes + :caption: Useful patterns :hidden: planes/filter_wheel planes/rb_element planes/translation_stage + +.. _examples.radiometry: + Radiometry ========== + .. toctree:: :caption: Radiometry :hidden: @@ -82,3 +87,33 @@ Radiometry radiometry/source_defocus +.. _examples.advanced: + +Advanced usage +============== + +.. grid:: 3 + + .. grid-item-card:: + :link: matlab_interface + :link-type: doc + :margin: 2 2 0 0 + + .. image:: /_static/img/psf.png + :width: 175px + :align: center + + MATLAB interface class + + +.. toctree:: + :caption: Advanced usage + :hidden: + + matlab_interface + + + + + + diff --git a/docs/examples/matlab/matlab_interface.rst b/docs/examples/matlab_interface.rst similarity index 97% rename from docs/examples/matlab/matlab_interface.rst rename to docs/examples/matlab_interface.rst index 9bf60a3..a8a04a2 100644 --- a/docs/examples/matlab/matlab_interface.rst +++ b/docs/examples/matlab_interface.rst @@ -1,7 +1,7 @@ -.. _cookbook-matlab: +.. _examples.matlab_interface: -Simple MATLAB Interface Class -============================= +MATLAB interface class +====================== Consider the following simple Lentil model which consists of an instrument, optical system, and detector: diff --git a/docs/examples/simple.rst b/docs/examples/simple.rst index 7dce35e..a0da1b3 100644 --- a/docs/examples/simple.rst +++ b/docs/examples/simple.rst @@ -1,8 +1,8 @@ .. _examples.simple_example: -******************************* -A simple diffraction simulation -******************************* +***************************** +Simple diffraction simulation +***************************** This is an example that demonstrates the core functionality of Lentil. It is mainly written for new users. More detailed examples and specific design patterns are available :ref:`here`. diff --git a/docs/user/advanced/matlab.rst b/docs/user/advanced/matlab.rst index 7fa2761..ec452ce 100644 --- a/docs/user/advanced/matlab.rst +++ b/docs/user/advanced/matlab.rst @@ -56,7 +56,7 @@ directory alongside the ``.m`` interfaces. This simplifies the end user experien because it does not require any additional path modification or management to use the model. -For an example, see: :ref:`cookbook-matlab`. +For an example, see: :ref:`examples.matlab_interface`. Finally, a few links that may be helpful when developing a MATLAB interface: diff --git a/docs/user/fundamentals/planes.rst b/docs/user/fundamentals/planes.rst index 5c58903..0c93640 100644 --- a/docs/user/fundamentals/planes.rst +++ b/docs/user/fundamentals/planes.rst @@ -329,7 +329,7 @@ a custom subclass of either |Plane| or |Pupil| should be defined. The exact implementation details will vary by application, but a simple example of a tip-tilt mirror where the plane's OPD is computed dynamically based on the state `x` is provided below. Additional examples can be found in Model Patterns under -:ref:`patterns.planes`. +:ref:`examples.useful_patterns`. .. code-block:: python3