From 487966b57a8914bb42f9235c122b8f6e27c17eb3 Mon Sep 17 00:00:00 2001 From: daquinteroflex Date: Fri, 7 Jun 2024 12:06:12 +0200 Subject: [PATCH] :books: Multiple docs fixes and improvements --- CHANGELOG.md | 2 + .../tidy3d.SimulationData.rst | 5 - docs/api/abstract_base.rst | 17 ++- docs/api/abstract_models.rst | 68 +++++------- docs/api/constants.rst | 9 +- docs/api/eme/index.rst | 4 +- docs/api/heat/boundary_conditions.rst | 6 +- docs/api/index.rst | 2 + docs/api/mediums.rst | 10 ++ docs/api/plugins/adjoint.rst | 2 +- docs/api/plugins/autograd.rst | 2 +- docs/api/plugins/design.rst | 6 +- docs/api/plugins/index.rst | 22 ++-- docs/api/plugins/invdes.rst | 14 +-- docs/conf.py | 87 +++++++++++++-- docs/development/documentation.rst | 21 +++- docs/development/index.rst | 14 +-- docs/development/installation.rst | 27 ++--- .../introduction/code_quality_principles.rst | 104 ++++++++++++++++++ docs/development/introduction/index.rst | 26 +++++ .../{ => introduction}/project_structure.rst | 6 +- .../introduction/understanding_poetry.rst | 96 ++++++++++++++++ .../understanding_virtual_environments.rst | 64 +++++++++++ docs/development/recommendations.rst | 4 +- docs/development/release/documentation.rst | 2 +- docs/development/release/flow.rst | 80 +++++++++++--- docs/development/release/version.rst | 5 +- docs/development/usage.rst | 6 +- docs/faq | 2 +- docs/index.rst | 2 +- docs/lectures/fdtd_workshop.rst | 18 +++ docs/lectures/index.rst | 3 + docs/notebooks | 2 +- tidy3d/components/eme/grid.py | 4 +- tidy3d/web/api/webapi.py | 2 +- tidy3d/web/cli/develop/documentation.py | 4 +- tidy3d/web/core/task_info.py | 97 ++++++++++++++-- 37 files changed, 683 insertions(+), 162 deletions(-) delete mode 100644 docs/api/_custom_autosummary/tidy3d.SimulationData.rst create mode 100644 docs/development/introduction/code_quality_principles.rst create mode 100644 docs/development/introduction/index.rst rename docs/development/{ => introduction}/project_structure.rst (97%) create mode 100644 docs/development/introduction/understanding_poetry.rst create mode 100644 docs/development/introduction/understanding_virtual_environments.rst create mode 100644 docs/lectures/fdtd_workshop.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b3588aa6d..92f14d40d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,5 @@ +# Changelog + All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), diff --git a/docs/api/_custom_autosummary/tidy3d.SimulationData.rst b/docs/api/_custom_autosummary/tidy3d.SimulationData.rst deleted file mode 100644 index 9b98306974..0000000000 --- a/docs/api/_custom_autosummary/tidy3d.SimulationData.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. autosummary:: - :recursive: - :toctree: ../_autosummary/ - - tidy3d.components.base.Tidy3dBaseModel.from_file \ No newline at end of file diff --git a/docs/api/abstract_base.rst b/docs/api/abstract_base.rst index 2eee39fe86..9934fa8e21 100644 --- a/docs/api/abstract_base.rst +++ b/docs/api/abstract_base.rst @@ -3,15 +3,24 @@ Abstract Base Models ===================== -Base classes that represent abstractions of the core elements of a Simulation. +Base classes that represent abstractions of the core elements of a common components. Provide inherited functionality. .. autosummary:: :toctree: _autosummary/ :template: module.rst - tidy3d.components.base_sim.simulation.AbstractSimulation + tidy3d.components.base_sim.data.sim_data.AbstractSimulationData tidy3d.components.base_sim.monitor.AbstractMonitor + tidy3d.components.base_sim.simulation.AbstractSimulation tidy3d.components.base_sim.source.AbstractSource - tidy3d.components.source.Source - tidy3d.components.monitor.Monitor + tidy3d.components.data.dataset.AbstractFieldDataset + tidy3d.components.data.monitor_data.AbstractFieldProjectionData + tidy3d.components.parameter_perturbation.AbstractPerturbation + tidy3d.components.parameter_perturbation.AbstractPerturbation + tidy3d.components.medium.AbstractCustomMedium + tidy3d.components.medium.AbstractMedium + tidy3d.components.simulation.AbstractYeeGridSimulation + tidy3d.components.structure.AbstractStructure + tidy3d.components.time.AbstractTimeDependence + diff --git a/docs/api/abstract_models.rst b/docs/api/abstract_models.rst index 89720f8d23..462ea14348 100644 --- a/docs/api/abstract_models.rst +++ b/docs/api/abstract_models.rst @@ -1,57 +1,47 @@ .. currentmodule:: tidy3d -Abstract Models +Base Models =============== -These are some classes that are used to organize the tidy3d components, but aren't to be used directly in the code. Documented here mainly for reference. +These are some classes that are used to organize the tidy3d components, but aren't to be used directly in the code. Documented here mainly for reference of inherited components. .. autosummary:: :toctree: _autosummary/ :template: module.rst + tidy3d.Geometry tidy3d.components.base.Tidy3dBaseModel - tidy3d.components.base_sim.simulation.AbstractSimulation - tidy3d.components.simulation.AbstractYeeGridSimulation tidy3d.components.boundary.AbsorberSpec - tidy3d.Geometry + tidy3d.components.data.data_array.DataArray + tidy3d.components.data.dataset.FieldDataset + tidy3d.components.data.dataset.FieldTimeDataset + tidy3d.components.data.dataset.ModeSolverDataset + tidy3d.components.data.monitor_data.ElectromagneticFieldData + tidy3d.components.data.monitor_data.MonitorData + tidy3d.components.data.sim_data.SimulationData tidy3d.components.geometry.base.Centered - tidy3d.components.geometry.base.Planar tidy3d.components.geometry.base.Circular - tidy3d.components.medium.AbstractMedium - tidy3d.components.medium.AbstractCustomMedium - tidy3d.components.medium.DispersiveMedium + tidy3d.components.geometry.base.Planar + tidy3d.components.geometry.base.SimplePlaneIntersection + tidy3d.components.grid.grid_spec.GridSpec1d + tidy3d.components.lumped_element.LumpedElement tidy3d.components.medium.CustomDispersiveMedium - tidy3d.components.structure.AbstractStructure - tidy3d.components.source.SourceTime - tidy3d.components.source.Source - tidy3d.components.source.FieldSource - tidy3d.components.source.CurrentSource - tidy3d.components.source.ReverseInterpolatedSource + tidy3d.components.medium.DispersiveMedium + tidy3d.components.monitor.FreqMonitor + tidy3d.components.monitor.Monitor + tidy3d.components.monitor.PlanarMonitor + tidy3d.components.monitor.TimeMonitor tidy3d.components.source.AngledFieldSource - tidy3d.components.source.PlanarSource - tidy3d.components.source.DirectionalSource tidy3d.components.source.BroadbandSource - tidy3d.components.source.VolumeSource + tidy3d.components.source.CurrentSource + tidy3d.components.source.DirectionalSource + tidy3d.components.source.FieldSource + tidy3d.components.source.PlanarSource tidy3d.components.source.Pulse - tidy3d.components.monitor.Monitor - tidy3d.components.monitor.FreqMonitor - tidy3d.components.monitor.TimeMonitor - tidy3d.components.monitor.AbstractFieldMonitor - tidy3d.components.monitor.AbstractFluxMonitor - tidy3d.components.monitor.PlanarMonitor - tidy3d.components.monitor.AbstractFieldProjectionMonitor - tidy3d.components.lumped_element.LumpedElement - tidy3d.components.grid.grid_spec.GridSpec1d - tidy3d.components.base_sim.data.sim_data.SimulationData - tidy3d.components.data.sim_data.AbstractYeeGridSimulationData - tidy3d.components.data.sim_data.SimulationData - tidy3d.components.data.data_array.DataArray - tidy3d.components.data.monitor_data.MonitorData - tidy3d.components.data.monitor_data.AbstractFieldProjectionData - tidy3d.components.data.monitor_data.ElectromagneticFieldData - tidy3d.components.data.monitor_data.AbstractMonitorData - tidy3d.components.data.dataset.AbstractFieldDataset - tidy3d.components.data.dataset.FieldDataset - tidy3d.components.data.dataset.FieldTimeDataset - tidy3d.components.data.dataset.ModeSolverDataset + tidy3d.components.source.ReverseInterpolatedSource + tidy3d.components.source.Source + tidy3d.components.source.SourceTime + tidy3d.components.source.VolumeSource + + diff --git a/docs/api/constants.rst b/docs/api/constants.rst index c109b83406..6a2c0ebca5 100644 --- a/docs/api/constants.rst +++ b/docs/api/constants.rst @@ -4,7 +4,7 @@ Constants ========= Physical Constants ------------------- +--------------------- .. autosummary:: :toctree: _autosummary/ @@ -27,10 +27,9 @@ Tidy3D Special Constants :template: module.rst tidy3d.constants.inf - tidy3d.constants.PEC Tidy3D Configuration --------------------- +--------------------- .. autosummary:: :toctree: _autosummary/ @@ -39,7 +38,7 @@ Tidy3D Configuration tidy3d.config.Tidy3dConfig Default Absorber Parameters ---------------------------- +---------------------------- .. autosummary:: :toctree: _autosummary/ @@ -83,7 +82,7 @@ Units Precision & Comparator Values ---------------------------- +------------------------------ .. autosummary:: :toctree: _autosummary/ diff --git a/docs/api/eme/index.rst b/docs/api/eme/index.rst index 353a2e472d..48b58bc2b3 100644 --- a/docs/api/eme/index.rst +++ b/docs/api/eme/index.rst @@ -1,5 +1,5 @@ -EME -============= +EME |:rainbow:| +=============== .. toctree:: :hidden: diff --git a/docs/api/heat/boundary_conditions.rst b/docs/api/heat/boundary_conditions.rst index 7feb741181..ddbfffc303 100644 --- a/docs/api/heat/boundary_conditions.rst +++ b/docs/api/heat/boundary_conditions.rst @@ -4,7 +4,7 @@ Thermal Boundary Conditions ----------------------------- Specifications -'''''''''''''''''' +^^^^^^^^^^^^^^^^^ .. autosummary:: :toctree: ../_autosummary/ @@ -14,7 +14,7 @@ Specifications Types -'''''''''''''''''' +^^^^^^^^^^^^^^^^^ .. autosummary:: :toctree: ../_autosummary/ @@ -26,7 +26,7 @@ Types Placement -'''''''''''''''''' +^^^^^^^^^^^^^^^^^ .. autosummary:: :toctree: ../_autosummary/ diff --git a/docs/api/index.rst b/docs/api/index.rst index b53e54ca65..66f1d16452 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -14,6 +14,7 @@ API |:computer:| sources monitors mode + field_projector lumped_elements discretization subpixel_averaging @@ -37,6 +38,7 @@ API |:computer:| .. include:: /api/sources.rst .. include:: /api/monitors.rst .. include:: /api/mode.rst +.. include:: /api/field_projector.rst .. include:: /api/lumped_elements.rst .. include:: /api/discretization.rst .. include:: /api/subpixel_averaging.rst diff --git a/docs/api/mediums.rst b/docs/api/mediums.rst index adbc2fe751..2bf2e8e275 100644 --- a/docs/api/mediums.rst +++ b/docs/api/mediums.rst @@ -116,3 +116,13 @@ Material Library .. toctree:: material_library + + +Abstract Classes +----------------- + +.. autosummary:: + :toctree: _autosummary/ + + tidy3d.components.medium.AbstractPerturbationMedium + tidy3d.components.medium.NonlinearModel \ No newline at end of file diff --git a/docs/api/plugins/adjoint.rst b/docs/api/plugins/adjoint.rst index 6ce31d2d94..97b8252e3f 100644 --- a/docs/api/plugins/adjoint.rst +++ b/docs/api/plugins/adjoint.rst @@ -5,7 +5,7 @@ Adjoint .. toctree:: - ../../../tidy3d/plugins/adjoint/README + ./../../../tidy3d/plugins/adjoint/README.md .. autosummary:: :toctree: ../_autosummary/ diff --git a/docs/api/plugins/autograd.rst b/docs/api/plugins/autograd.rst index 427fecc9a8..1fdb5bc2ba 100644 --- a/docs/api/plugins/autograd.rst +++ b/docs/api/plugins/autograd.rst @@ -5,7 +5,7 @@ Automatic Differentiation with Autograd .. toctree:: - ../../../tidy3d/plugins/autograd/README + ./../../../tidy3d/plugins/autograd/README .. autosummary:: :toctree: ../_autosummary/ diff --git a/docs/api/plugins/design.rst b/docs/api/plugins/design.rst index 653b2c5c0d..b4f44283c2 100644 --- a/docs/api/plugins/design.rst +++ b/docs/api/plugins/design.rst @@ -11,14 +11,14 @@ Design Space Exploration :toctree: ../_autosummary/ :template: module.rst - tidy3d.plugins.design.Parameter + tidy3d.plugins.design.parameter.Parameter tidy3d.plugins.design.ParameterFloat tidy3d.plugins.design.ParameterInt tidy3d.plugins.design.ParameterAny - tidy3d.plugins.design.Method + tidy3d.plugins.design.method.Method tidy3d.plugins.design.MethodGrid tidy3d.plugins.design.MethodMonteCarlo tidy3d.plugins.design.MethodRandomCustom tidy3d.plugins.design.MethodRandom tidy3d.plugins.design.DesignSpace - tidy3d.plugins.design.Results + tidy3d.plugins.design.Result diff --git a/docs/api/plugins/index.rst b/docs/api/plugins/index.rst index d60fc3691a..b21f411a98 100644 --- a/docs/api/plugins/index.rst +++ b/docs/api/plugins/index.rst @@ -4,17 +4,17 @@ Plugins .. toctree:: :hidden: - mode_solver - dispersion - polyslab - smatrix - resonance - autograd - adjoint - design - invdes - waveguide - microwave + ./mode_solver + ./dispersion + ./polyslab + ./smatrix + ./resonance + ./autograd + ./adjoint + ./invdes + ./design + ./waveguide + ./microwave .. include:: /api/plugins/mode_solver.rst diff --git a/docs/api/plugins/invdes.rst b/docs/api/plugins/invdes.rst index cbd85ec108..ff2bfe27f6 100644 --- a/docs/api/plugins/invdes.rst +++ b/docs/api/plugins/invdes.rst @@ -5,7 +5,7 @@ Inverse Design Plugin .. toctree:: - ../../../tidy3d/plugins/invdes/README + ./../../../tidy3d/plugins/invdes/README.md .. autosummary:: :toctree: ../_autosummary/ @@ -18,9 +18,9 @@ Inverse Design Plugin tidy3d.plugins.invdes.InverseDesignMulti tidy3d.plugins.invdes.InverseDesignResult tidy3d.plugins.invdes.AdamOptimizer - tidy3d.plugins.invdes.get_amps - tidy3d.plugins.invdes.get_field_component - tidy3d.plugins.invdes.get_intensity - tidy3d.plugins.invdes.sum_array - tidy3d.plugins.invdes.sum_abs_squared - tidy3d.plugins.invdes.get_phase + tidy3d.plugins.invdes.utils.get_amps + tidy3d.plugins.invdes.utils.get_field_component + tidy3d.plugins.invdes.utils.get_intensity + tidy3d.plugins.invdes.utils.sum_array + tidy3d.plugins.invdes.utils.sum_abs_squared + tidy3d.plugins.invdes.utils.get_phase diff --git a/docs/conf.py b/docs/conf.py index d020264b78..ff8bde333e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,6 +18,7 @@ # absolute, like shown here. # import datetime +import logging import os import re import subprocess @@ -32,14 +33,14 @@ # TODO sort this out here = os.path.abspath(os.path.dirname(__file__)) sys.path.insert(0, os.path.abspath("_ext")) -sys.path.insert(0, os.path.abspath("source")) -sys.path.insert(0, os.path.abspath("notebooks")) -sys.path.insert(0, os.path.abspath("")) -sys.path.insert(0, os.path.abspath("../tidy3d")) -sys.path.insert(0, os.path.abspath("../tidy3d/components")) -sys.path.insert(0, os.path.abspath("../tidy3d/components/base_sim")) -sys.path.insert(0, os.path.abspath("../tidy3d/web")) -sys.path.insert(0, os.path.abspath("../tidy3d/plugins")) +# sys.path.insert(0, os.path.abspath("source")) +# sys.path.insert(0, os.path.abspath("notebooks")) +# # sys.path.insert(0, os.path.abspath("")) +# sys.path.insert(0, os.path.abspath("../tidy3d")) +# sys.path.insert(0, os.path.abspath("../tidy3d/components")) +# sys.path.insert(0, os.path.abspath("../tidy3d/components/base_sim")) +# sys.path.insert(0, os.path.abspath("../tidy3d/web")) +# sys.path.insert(0, os.path.abspath("../tidy3d/plugins")) # -- Project information ----------------------------------------------------- @@ -75,7 +76,18 @@ copybutton_prompt_is_regexp = True custom_sitemap_excludes = [r"/notebooks/"] # divparams_enable_postprocessing = True # TODO FIX -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints", "faq/_faqs/*"] +exclude_patterns = [ + "_docs/", + "_templates/", + "_ext/", + "**.ipynb_checkpoints", + ".DS_Store", + "Thumbs.db", + "faq/_faqs/*", + "scripts/*", + "tests/*", + ".github/*", +] extensions = [ "IPython.sphinxext.ipython_directive", "IPython.sphinxext.ipython_console_highlighting", @@ -152,6 +164,17 @@ } latex_engine = "xelatex" language = "en" +include_patterns = [ + "tidy3d/*", + "faq/docs/**", + "notebooks/*.ipynb", + "notebooks/docs/*", + "**.rst", + "**.png", + "**.svg", + "**.txt", + "**/sitemap.xml", +] napoleon_google_docstring = False napoleon_numpy_docstring = True napoleon_include_init_with_doc = False @@ -239,3 +262,49 @@ # # # # 'figure_align': 'htbp', # } + + +class ImportWarningFilter(logging.Filter): + def filter(self, record): + # Suppress specific autosummary import warnings + message = record.getMessage() + if "autosummary: failed to import" in message and any( + phrase in message + for phrase in ["ModuleNotFoundError", "ValueError", "KeyError", "AttributeError"] + ): + return False + return True + + +class AutosummaryFilter(logging.Filter): + """ + This is basically a hack until I finally get round to writing our own custom sphinx extension which will customise + the way we represent our documentation properly. The goal of adding these filters is that at least we'll get useful + information on errors, rather than those related to the docs memory - stub page generation tradeoff. + """ + + def filter(self, record): + # Suppress "autosummary: stub file not found" warnings + if "autosummary" in record.getMessage() and "stub file not found" in record.getMessage(): + return False + return True + + +def add_import_warning_filter(app): + # Get the Sphinx logger + logger = logging.getLogger("sphinx") + # Add the custom filter to the logger + logger.addFilter(ImportWarningFilter()) + + +def add_autosummary_filter(app): + # Get the Sphinx logger + logger = logging.getLogger("sphinx") + # Add the custom filter to the logger + logger.addFilter(AutosummaryFilter()) + + +def setup(app): + # Apply the custom filter early in the build process + app.connect("builder-inited", add_autosummary_filter) + app.connect("builder-inited", add_import_warning_filter) diff --git a/docs/development/documentation.rst b/docs/development/documentation.rst index 1773ac7ed5..09efe18e56 100644 --- a/docs/development/documentation.rst +++ b/docs/development/documentation.rst @@ -21,7 +21,7 @@ Common Updates -------------- Adding a new notebook -'''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^ This process is self-contained in ``tidy3d-notebooks``. @@ -34,7 +34,7 @@ This submodule commit process can be done by running ``git add docs/notebooks`` If you want to locally develop notebooks in ``tidy3d/docs/notebooks`` then just use that submodule as your main development repository and commit to your local branch. Then when you are ready to publish, just make sure to commit the submodule to the latest ``develop`` branch. You can then build the documentation locally easily using this approach before it is published. Updating Docstrings -''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^ The ``tidy3d develop`` suite includes a utility command ``replace-in-files``, which is designed to recursively find and replace strings in files within a specified directory. This functionality is particularly useful for updating docstrings across the codebase when there are changes in the API, ensuring that the documentation remains consistent with multiple version updates. This is useful when updating the API and you want to update the docstrings to reflect the changes from multiple versions. @@ -88,4 +88,19 @@ Further Guidance - The sphinx warnings are OK as long as the build occurs, errors will cause the crash the build. - Make sure all your internal API references start with ``tidy3d.`` -- In notebooks, always have absolute links, otherwise the links will break when the user downloads them. \ No newline at end of file +- In notebooks, always have absolute links, otherwise the links will break when the user downloads them. + + +Writing Documentation +^^^^^^^^^^^^^^^^^^^^^^^^ + +... raw:: + + Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, this convention is used in Python Developer’s Guide for documenting which you may follow: + # with overline, for parts + * with overline, for chapters + = for sections + - for subsections + ^ for subsubsections + " for paragraphs + diff --git a/docs/development/index.rst b/docs/development/index.rst index ac79cf547c..3f4a363065 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -2,22 +2,20 @@ Development Guide |:hammer_and_wrench:| ******************************************************************** -Welecome to the ``tidy3d`` developers guide! These are just some recommendations I've compiled, but we can change anything as we think might help the development cycle more. +Welecome to the ``tidy3d`` developers guide! + .. toctree:: - :maxdepth: 1 - :hidden: + :maxdepth: 2 - project_structure + introduction/index installation usage - documentation recommendations release/index -.. include:: /development/project_structure.rst +.. include:: /development/introduction/index.rst .. include:: /development/installation.rst .. include:: /development/usage.rst -.. include:: /development/documentation.rst .. include:: /development/recommendations.rst -.. include:: /development/release/index.rst \ No newline at end of file +.. include:: /development/release/index.rst diff --git a/docs/development/installation.rst b/docs/development/installation.rst index d485b788e8..d456024441 100644 --- a/docs/development/installation.rst +++ b/docs/development/installation.rst @@ -1,20 +1,15 @@ -Installation -============== - -Beginners Guide -^^^^^^^^^^^^^^^ - - +Development Environment Installation +===================================== The Fast Lane -^^^^^^^^^^^^^ +-------------- Maybe you already have ``tidy3d`` installed in some form. After installing version ``tidy3d>=2.6``, you can use a few terminal commands to set you up on the correct environment and perform common development tasks. Just run in your terminal, :code:`tidy3d develop` to get the latest list of commands. It does not matter how you have installed ``tidy3d`` before as long as you have any form of ``tidy3d>=2.6`` in your environment. This can help you transition from a standard user installation to a development environment installation. Quick Start -'''''''''''' +^^^^^^^^^^^^^ Instructions for anyone who wants to migrate to the development flow from a version before 2.6: @@ -36,7 +31,7 @@ Now you can run the following ``tidy3d`` cli commands to test them. Automatic Environment Installation *Beta* -'''''''''''''''''''''''''''''''''''''''''' +"""""""""""""""""""""""""""""""""""""""""""""" If you are transitioning from the old development flow, to this new one, there are a list of commands you can run to make your life easier and set you up well: @@ -52,7 +47,7 @@ The way this command works is dependent on the operating system you are running. This command will first check if you already have installed the development requirements, and if not, it will run the installation scripts for ``pipx``, ``poetry``, and ask you to install the required version of ``pandoc``. It will also install the development requirements and ``tidy3d`` package in a specific ``poetry`` environment. Environment Verification -'''''''''''''''''''''''' +"""""""""""""""""""""""""""" If you rather install ``poetry``, ``pipx`` and ``pandoc`` yourself, you can run the following command to verify that your environment conforms to the reproducible development environment which would be equivalent to the one installed automatically above and described in :ref:`The Detailed Lane`. @@ -61,16 +56,14 @@ If you rather install ``poetry``, ``pipx`` and ``pandoc`` yourself, you can run tidy3d develop verify-dev-environment -.. _The Detailed Lane:: - The Detailed Lane -^^^^^^^^^^^^^^^^^ +------------------ If you do not have any of the above tools already installed and want to install them manually, let's go through the process of setting things up from scratch: Environment Requirements -'''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^ Make sure you have installed ``pipx``. We provide common installation flows below: @@ -182,7 +175,7 @@ If you want to contribute to the project, read the following section: More Contribution Requirements -'''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you want to contribute to the development of ``tidy3d``, you can follow the instructions below to set up your development environment. This will allow you to run the tests, build the documentation, and run the examples. Another thing you need to do before committing to the project is to install the pre-commit hooks. This will ensure that your code is formatted correctly and passes the tests before you commit it. To do this, run the following command: @@ -204,7 +197,7 @@ You can also run the checks manually on all files by running the following comma Packaging Equivalent Functionality -''''''''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This package installation process should be approximately equivalent to the previous ``setup.py`` installation flow. Independent of the ``poetry`` development flow, it is possible to run any of the following commands in any particular virtual environment you have configured: diff --git a/docs/development/introduction/code_quality_principles.rst b/docs/development/introduction/code_quality_principles.rst new file mode 100644 index 0000000000..bf8890168b --- /dev/null +++ b/docs/development/introduction/code_quality_principles.rst @@ -0,0 +1,104 @@ +Code Quality Principles +------------------------ + +When writing a code snippet, remember the saying: "code is read more than written". We want to maintain our code maintainable, readable and high quality. + +Linting & Formatting +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To maintain code quality, we use `Ruff `_ as a linter and code formatter. A linter analyzes code to identify and flag potential errors, stylistic issues, and code that doesn't adhere to defined standards (such as `PEP8 `_). A code formatter automatically restructures the code to ensure it is consistently styled and properly formatted, making it consistent across the code base. + +Run ``ruff format`` to format all Python files: + +.. code-block:: bash + + poetry run ruff format . + +Run ``ruff check`` to check for style and other issues. Many common warnings can be automatically fixed with the ``--fix`` flag: + +.. code-block:: bash + + poetry run ruff check tidy3d --fix + +The configuration defining what ``ruff`` will correct lives in ``pyproject.toml`` under the ``[tool.ruff]`` section. + +When submitting code, for tests to pass, ``ruff`` should give no warnings. + +Documentation +^^^^^^^^^^^^^^^ + +Document all code you write using `NumPy-style docstrings `_. + +Testing +------- + +Here we will discuss how tests are defined and run in Tidy3d. + +Unit Testing +^^^^^^^^^^^^^^ + +The tests live in ``tests/`` directory. + +We use `pytest `_ package for our testing. + +To run all of the tests, call: + +.. code-block:: bash + + poetry run pytest -rA tests + +This command will trigger ``pytest`` to go through each file in ``tests/`` called ``test*.py`` and run each function in that file with a name starting with ``test``. + +If all of these functions run without any exceptions being raised, the tests pass! + +The specific configuration we use for ``pytest`` lives in the ``[tool.pytest.ini_options]`` section of ``pyproject.toml``. + +These tests are automatically run when code is submitted using GitHub Actions, which tests on Python 3.9 through 3.12 running on Ubuntu, MacOS, and Windows operating systems, as well as Flexcompute's servers. + +Note: The ``-rA`` flag is optional but produces output that is easily readable. + +Note: You may notice warnings and errors in the ``pytest`` output, this is because many of the tests intentionally trigger these warnings and errors to ensure they occur in certain situations. The important information about the success of the test is printed out at the bottom of the ``pytest`` output for each file. + +To get a code coverage report: + +.. code-block:: bash + + pip install pytest-cov + +if not already installed + +To run coverage tests with results printed to STDOUT: + +.. code-block:: bash + + pytest tests --cov-report term-missing --cov=tidy3d + +To run coverage tests and get output as .html (more intuitive): + +.. code-block:: bash + + pytest tests --cov-report=html --cov=tidy3d + open htmlcov/index.html + +Automated Testing +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We use GitHub Actions to perform these tests automatically and across different operating systems. + +On commits, each of the ``pytest`` tests are run using Python 3.9 - 3.12 installed on Ubuntu, MacOS, and Windows operating systems. + +See the "actions" tab for details on previous tests and ``.github/workflows/run_tests.yml`` for the configuration and to see the specific tests run. + +See `this `_ for more explanation. + +Other Tests +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are additional tests in both the `documentation `_ and our private backend code. The same practices outlined here apply to those tests. + +More Resources on Testing +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A useful explanation for those curious to learn more about the reasoning behind these decisions: + +`https://www.youtube.com/watch?v=DhUpxWjOhME ` \ No newline at end of file diff --git a/docs/development/introduction/index.rst b/docs/development/introduction/index.rst new file mode 100644 index 0000000000..e9301961eb --- /dev/null +++ b/docs/development/introduction/index.rst @@ -0,0 +1,26 @@ +An Introduction to the Development Flow +======================================== + +This page hopefully will get you started to develop Tidy3D. + +**TLDR:** + +- Branch off of the target branch (usually ``develop`` or ``pre/x.x``), work on your branch, and submit a PR when ready. +- Use isolated development environments with ``poetry``. +- Use ``ruff`` to lint and format code, and install the pre-commit hook via ``pre-commit install`` to automate this. +- Document code using NumPy-style docstrings. +- Write unit tests for new features and try to maintain high test coverage. + +.. toctree:: + :maxdepth: 1 + + understanding_virtual_environments + understanding_poetry + code_quality_principles + project_structure + + +.. include:: /development/introduction/understanding_virtual_environments.rst +.. include:: /development/introduction/understanding_poetry.rst +.. include:: /development/introduction/code_quality_principles.rst +.. include:: /development/introduction/project_structure.rst \ No newline at end of file diff --git a/docs/development/project_structure.rst b/docs/development/introduction/project_structure.rst similarity index 97% rename from docs/development/project_structure.rst rename to docs/development/introduction/project_structure.rst index 736ef5512c..522700ea4f 100644 --- a/docs/development/project_structure.rst +++ b/docs/development/introduction/project_structure.rst @@ -1,5 +1,5 @@ -Project Structure -================= +``tidy3d`` Project Structure +----------------------------- As of ``tidy3d>=2.6``, the frontend has been restructured to improve the development cycle. The project directories follow the following structure, which is derived from some recommended `Python project architecture guides `_. This is a handy structure because many tools, such as ``sphinx``, integrate quite well with this type of project layout. @@ -31,7 +31,7 @@ It is important to note the new tools we are using to manage our development env - ``pipx`` Important Branches ------------------- +^^^^^^^^^^^^^^^^^^^ We currently have *three* main branches that have to be kept track of when creating a release, each with different functionality. diff --git a/docs/development/introduction/understanding_poetry.rst b/docs/development/introduction/understanding_poetry.rst new file mode 100644 index 0000000000..a415066a83 --- /dev/null +++ b/docs/development/introduction/understanding_poetry.rst @@ -0,0 +1,96 @@ +Using `poetry` for package management +-------------------------------------- + +What is Poetry +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`Poetry `_ is a package management tool for Python. + +Among other things, it provides a nice way to: + +- Manage dependencies +- Publish packages +- Set up and use virtual environments + +Effectively, it is a command line utility (similar to ``pip``) that is a bit more convenient and allows more customization. + +Why do we want to use it +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. To improve our dependency management, which is used to be all over the place. We have several ``requirements.txt`` files that get imported into ``setup.py`` and parsed depending on the extra arguments passed to ``pip install``. ``Poetry`` handles this much more elegantly through a ``pyproject.toml`` file that defines the dependency configuration very explicitly in a simple data format. +2. Reproducible development virtual environments means that everyone is using the exact same dependencies, without conflicts. This also improves our packaging and release flow. + +How to install it? +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We provide custom installation instructions and an installation script on TODO ADD LINK SECTION. However, you can read more information here: see the poetry documentation for a guide to `installation `_ and `basic use `_. + + +Usage Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To add poetry to a project +"""""""""""""""""""""""""""" + +To initialize a new basic project with poetry configured, run: + +.. code-block:: bash + + poetry new poetry-demo + +To add poetry to an existing project, ``cd`` to the project directory and run: + +.. code-block:: bash + + poetry init + +Configuring dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The dependency configuration is in the editable file called ``pyproject.toml``. Here you can specify whatever dependencies you want in your project, their versions, and even different levels of dependencies (e.g., ``dev``). + +To add a dependency to the project (e.g., ``numpy``), run: + +.. code-block:: bash + + poetry add numpy + +You can then verify that it was added to the ``tool.poetry.dependencies`` section of ``pyproject.toml``. + +For many more options on defining dependencies, see `here `_. + +Virtual environments +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Now that the project has had poetry configured and the correct dependencies are specified, we can use poetry to run our scripts/shell commands from a virtual environment without much effort. There are a few ways to do this: + +**Poetry run**: One way is to precede any shell command you’d normally run with ``poetry run``. For example, if you want to run ``python tidy_script.py`` from the virtual environment set up by poetry, you’d do: + +.. code-block:: bash + + poetry run python tidy3d_script.py + +**Poetry shell**: + +If you want to open up a shell session with the environment activated, you can run: + +.. code-block:: bash + + poetry shell + +And then run your commands. To return to the original shell, run ``exit``. + +There are many more advanced options explained `here `_. + +Publishing Package +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To upload the package to PyPI: + +.. code-block:: bash + + poetry build + + poetry publish + +Note that some `configuration `_ must be set up before this would work properly. diff --git a/docs/development/introduction/understanding_virtual_environments.rst b/docs/development/introduction/understanding_virtual_environments.rst new file mode 100644 index 0000000000..165344cf57 --- /dev/null +++ b/docs/development/introduction/understanding_virtual_environments.rst @@ -0,0 +1,64 @@ +Understanding Virtual Environments +---------------------------------- + +Introduction +^^^^^^^^^^^^^ + +In larger projects, it's crucial to have a *separate* Python environment for each feature or branch you work on. This practice ensures isolation and reproducibility, simplifying testing and debugging by allowing issues to be traced back to specific environments. It also facilitates smoother integration and deployment processes, ensuring controlled and consistent development. +Managing multiple environments might seem daunting, but it's straightforward with the right tools. Follow the steps below to set up and manage your environments efficiently. + +Benefits +^^^^^^^^^^^^^ + +- **Isolation**: Avoids conflicts between dependencies of different features. +- **Reproducibility**: Each environment can be easily replicated. +- **Simplified Testing**: Issues are contained within their respective environments. +- **Smooth Integration**: Ensures features are developed in a consistent setting. + +Prerequisites +^^^^^^^^^^^^^^ + +Make sure that you have ``poetry`` installed. This can be done system-wide with ``pipx`` or within a ``conda`` environment. Note that we use ``conda`` only for setting up the interpreter (Python version) and ``poetry``, not for managing dependencies. +Refer to the official development guide for detailed instructions: + +`https://docs.flexcompute.com/projects/tidy3d/en/stable/development/index.html#installation `_ + +Setting Up a New Environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Check out the branch: + + .. code-block:: bash + + git checkout branch + +2. Set up the environment with ``conda`` (skip this step if you don’t use ``conda``): + + .. code-block:: bash + + conda create -n branch_env python=3.11 poetry + conda activate branch_env + poetry env use system + poetry env info # verify you're running the right environment now + +3. Install dependencies with ``poetry``: + + .. code-block:: bash + + poetry install -E dev + poetry run pre-commit install + +4. Update the environment when switching to a different branch: + + .. code-block:: bash + + poetry install -E dev + + + +Multiple Folders or Worktrees +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you have multiple folders (e.g., multiple clones or git worktrees), you will need to repeat the environment setup for each folder. Ensure that each folder has its own isolated environment. + +By following these steps, you can maintain isolated and reproducible environments for each branch and feature, leading to a more efficient and error-free development process. \ No newline at end of file diff --git a/docs/development/recommendations.rst b/docs/development/recommendations.rst index e2964df197..d6d3d042ea 100644 --- a/docs/development/recommendations.rst +++ b/docs/development/recommendations.rst @@ -50,7 +50,7 @@ However, if we do decide to commit with emojis, I believe it would be worth havi Package Speedup Best Practices ----------------------------- +-------------------------------- ``tidy3d`` is a pretty big project already, and will get bigger. We want to optimise the performance of the codebase throughout the multiple operations that we perform. @@ -77,7 +77,7 @@ This is because the latter will import the entire package, which is not necessar Managing Optional Dependencies On-The-Fly ----------------------------- +------------------------------------------ If you look within ``pyproject.toml``, it is possible to see that we have different packages relating to different functionalities that are optional. diff --git a/docs/development/release/documentation.rst b/docs/development/release/documentation.rst index 8b8050ce42..1f73fb01fc 100644 --- a/docs/development/release/documentation.rst +++ b/docs/development/release/documentation.rst @@ -19,7 +19,7 @@ The `latest` branch holds the state of the docs that we want to host in `latest` The `stable` version of the docs on our website is built based on the last version tag which is not a pre-release tag (no `rc` ending). Hot Fix & Submodule Updates -''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To make a “hot fix” (eg fix a typo, add a notebook, update the release FAQ), just update the ``latest`` branch in ``tidy3d`` repo. This should automatically sync to `tidy3d-docs`, and trigger a docs rebuild. **However, we should avoid this as this will cause the ``develop`` and ``latest branches`` to diverge.** Ideally, these hot fixes could wait until the next pre/post-release to be propagated through. diff --git a/docs/development/release/flow.rst b/docs/development/release/flow.rst index accac7adf3..55df801e72 100644 --- a/docs/development/release/flow.rst +++ b/docs/development/release/flow.rst @@ -1,15 +1,37 @@ +Feature Contribution +----------------------- + + + Feature Development Workflow ------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +1. Create a branch off of ``develop`` +"""""""""""""""""""""""""""""""""""""""" + +Our ``pre/x.x`` branches are where new features, bug fixes, and other things get added before a major release. To switch to the ``pre/x.x`` branch: + +.. code-block:: bash + + git checkout pre/x.x + +And then you can create a new branch from here with your GitHub username pre-pended: + +.. code-block:: bash + + git checkout -b myusername/cool-feature Currently most of our release development flow is made under the latest ``pre/*`` branch under the main frontend -tidy3d repository. You want to fork from this latest branch to develop your feature in order for it to be included -under that release. +tidy3d repository. You want to fork from this latest branch to develop your feature in order for it to be included under that release. We are using a variation of the `gitflow workflow `__ -- so this is the first thing to familiarize yourselves with. The -splitting of branches into ``main``, ``develop`` and separate feature -branches is as explained there. Most importantly, **all contributions +- so this is the first thing to familiarize yourselves with. The link provided explains it very well, but to summarize: features get added to a pre-release branch (``pre/x.x``), and once all the features for a particular release have been implemented, the pre-release branch gets merged into ``develop``. The ``latest`` branch holds the code we want most users to be using. When we wish to release a new version, we simply merge the state of ``develop`` into ``latest``, propagating all of the changes at once. We will describe this process in more detail below. + +When developing new features, we ask that you create a branch off of whichever branch you aim to contribute to. This is typically either the current pre-release branch named ``pre/x.x`` or ``develop`` depending on what stage of development we are currently in. You then work on your branch, and when the feature is ready to merge in, we prefer ``git rebase`` to ``git merge``. This creates a cleaner, linear history. You can read about why we do it and what a rebase is at `this link `_. And see Momchil’s more specific notes `here `_. + +Most importantly, **all contributions should happen through a PR from a feature branch into the develop branch.** @@ -29,23 +51,36 @@ a clean branch on your machine. .. code-block:: bash # from the main tidy3d frontend repo - git checkout develop - git pull origin develop + git checkout pre/x.x + git pull origin pre/x.x git checkout -b my_name/new_feature +2. Writing code +"""""""""""""""""""""""""""""""""""""""" + +Develop your code in this new branch, committing your changes when it seems like a natural time to “save your progress”. + +If you are working on a new feature, make sure you add a line in the `CHANGELOG.md `_ file (if it exists in that repository) to summarize your changes. + + +3. Create a pull request on GitHub +"""""""""""""""""""""""""""""""""""""""" + +First, push your changes to your branch on GitHub. + +In the GitHub website, create a pull request to merge your branch into ``pre/x.x``. -Create your feature rebase -'''''''''''''''''''''''''''''' +Write some comments or a summary of changes in your pull request to be clear about what is being added/changed and why. Before rebasing, you should make sure you have the latest version of ``develop``, in case other work has been merged meanwhile. .. code-block:: bash - git checkout develop - git pull origin develop + git checkout pre/x.x + git pull origin pre/x.x git checkout my_name/new_feature - git rebase -i develop + git rebase -i pre/x.x This will now open an editor that will allow you to edit the commits in the feature branch. There is plenty of explanations of the various @@ -76,8 +111,22 @@ rebasing has changed its history. git push -f origin my_name/new_feature -Submitting to PR -''''''''''''''''' + +4. Submit for review +""""""""""""""""""""" + +Every PR must have the following before it can be merged: + +- At least one review. +- A description in the CHANGELOG of what has been done. + +Every new major feature must also pass all of the following before it can be merged: + +- Frontend and backend tests by the developer (unless no code has changed on one or the other), as well as a new example notebook or a modification to an existing example notebook that utilizes the new feature. Intermediate reviews can happen, but these conditions must be met for the feature to begin to be considered for a merge. +- Ensure any known limitations are listed at the top message in the PR conversation (e.g., does the feature work with the mode solver? The auto grid? Does it work, but not as well as it should?). The feature can be merged given the limitations if we make a decision to do that, but only if an error or warning is issued whenever a user could encounter them, and after the list has been moved to another PR or an issue to keep track. +- If backend changes are present, review by one of the people well-versed with the solver (Momchil, Weiliang, Shashwat, Daniil). +- If frontend changes are present, review by any member of the team and additional approval by Momchil or Tyler. +- QA from any member of the team: playing around with the new feature and trying to find limitations. The goal is not to construct one successful example but to figure out if there is any allowed usage that may be problematic. An extra example notebook may or may not come out of this. After this, you can notify Momchil that the branch is ready to to be merged. In the comment you can optionally also say things like “Fixes @@ -94,4 +143,3 @@ rebasing allows you to clean everything up. feature, i.e. all PR comments have been addressed, etc. This is not critical, but is nicer to only rebase in the end so as not to muddle up the PR discussion when you force push the new branch (see below). - diff --git a/docs/development/release/version.rst b/docs/development/release/version.rst index d13ffa44ff..25f48ee05e 100644 --- a/docs/development/release/version.rst +++ b/docs/development/release/version.rst @@ -4,9 +4,8 @@ Releasing a new ``tidy3d`` version This document contains the relevant information to create and publish a new tidy3d version. Version Information Management -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``pyproject.toml`` is declarative (ie static) and provides information to the packaging tools like PyPi on what version is ``tidy3d``. However, we also have a ``version.py`` file so that we can dynamically query ``tidy3d.__version__`` within our python version. These two files need to be kept with the same version. This is achieved by using the ``bump-my-version`` utility as described in the following section. **These files should not be manually updated.** -The configuration of the way the version bumping occurs is described in the ``pyproject.toml``. - +The configuration of the way the version bumping occurs is described in the ``pyproject.toml``. \ No newline at end of file diff --git a/docs/development/usage.rst b/docs/development/usage.rst index 1bacada721..37a706fc98 100644 --- a/docs/development/usage.rst +++ b/docs/development/usage.rst @@ -2,7 +2,7 @@ Using the Development Flow ========================== Developing ``tidy3d`` with ``poetry`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------------------------- `poetry `_ is an incredibly powerful tool for reproducible package development environments and dependency management. @@ -19,7 +19,7 @@ It is important to note the function above is equivalent to ``pip install tidy3d ``poetry`` with an external virtual environment --------------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ It is recommended to use ``poetry`` for package development. However, there are some cases where you might need to use an external virtual environment for some operations. There are a few workarounds where you can leverage the reproducibility of the ``poetry`` managed environment with the freedom of a standard virtual environment. There are a few more instructions and explanations in `the poetry env docs `_ . F See the following example: @@ -35,7 +35,7 @@ It is recommended to use ``poetry`` for package development. However, there are There are also other methodologies of implementing common dependencies management. Common Utilities -^^^^^^^^^^^^^^^^ +"""""""""""""""""""" There are a range of handy development functions that you might want to use to streamline your development experience. diff --git a/docs/faq b/docs/faq index 1a74c4b7cb..802f861885 160000 --- a/docs/faq +++ b/docs/faq @@ -1 +1 @@ -Subproject commit 1a74c4b7cb1a1721fb0490e4510c0e30f0d03ac3 +Subproject commit 802f8618852493bbb70e437d02ef6a33594ca6bd diff --git a/docs/index.rst b/docs/index.rst index 803f501245..d99a5d16e3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -187,7 +187,7 @@ Further Information About our Solver Github Repositories -~~~~~~~~~~~~~~~~~ +-------------------- .. list-table:: :header-rows: 1 diff --git a/docs/lectures/fdtd_workshop.rst b/docs/lectures/fdtd_workshop.rst new file mode 100644 index 0000000000..36640fac72 --- /dev/null +++ b/docs/lectures/fdtd_workshop.rst @@ -0,0 +1,18 @@ +*************************** +Future-Ready FDTD Workshop +*************************** + +The Future-Ready FDTD Workshop Series is a collaborative effort between Tidy3D, iOptics, and Optica. The series aims to present a range of workshops focused on FDTD simulations for photonic devices. The workshop sessions took place from February 9th to March 8th, 2024, and covered theoretical foundations of concepts such as the FDTD method, Bragg filters and reflectors, multimode photonic design, photonic crystals, and inverse design. +Each session included a live demonstration of setting up and running an FDTD simulation. Additionally, a challenge was proposed to enhance participants' skills. Challenge solutions are available upon request through our technical support. + +`Lecture 1: The FDTD Method Demystified `_ + +`Lecture 2: Multimode Photonics Design Made Easy `_ + +`Lecture 3: Designing Filters and Reflectors with Bragg Gratings `_ + +`Lecture 4: Photonic Crystal Slabs Controlling and Confining Light on the Nanoscale `_ + +`Lecture 5: Inverse Design in Photonics An Introduction `_ + +More lectures coming soon! diff --git a/docs/lectures/index.rst b/docs/lectures/index.rst index 0c14387643..2ee7007591 100644 --- a/docs/lectures/index.rst +++ b/docs/lectures/index.rst @@ -8,7 +8,10 @@ Welcome to our lecture series! :hidden: fdtd101 + fdtd_workshop inversedesign + .. include:: /lectures/fdtd101.rst +.. include:: /lectures/fdtd_workshop.rst .. include:: /lectures/inversedesign.rst \ No newline at end of file diff --git a/docs/notebooks b/docs/notebooks index d1b1cbe270..dbfc67aed5 160000 --- a/docs/notebooks +++ b/docs/notebooks @@ -1 +1 @@ -Subproject commit d1b1cbe270e0969c05598f3c4d9742f4cb6eb50b +Subproject commit dbfc67aed533cb656ab2eeb3c1fad2e54e7ca906 diff --git a/tidy3d/components/eme/grid.py b/tidy3d/components/eme/grid.py index 7d63978dc0..21ed3317eb 100644 --- a/tidy3d/components/eme/grid.py +++ b/tidy3d/components/eme/grid.py @@ -14,7 +14,7 @@ from ..geometry.base import Box from ..grid.grid import Coords1D from ..mode import ModeSpec -from ..types import ArrayFloat1D, Axis, Coordinate, Size, TrackFreq, annotate_type +from ..types import ArrayFloat1D, Axis, Coordinate, Size, TrackFreq # grid limits MAX_NUM_MODES = 100 @@ -277,7 +277,7 @@ class EMECompositeGrid(EMEGridSpec): ... ) """ - subgrids: List[annotate_type(EMESubgridType)] = pd.Field( + subgrids: List[EMESubgridType] = pd.Field( ..., title="Subgrids", description="Subgrids in the composite grid." ) diff --git a/tidy3d/web/api/webapi.py b/tidy3d/web/api/webapi.py index 5868d6caf0..d8ba42822c 100644 --- a/tidy3d/web/api/webapi.py +++ b/tidy3d/web/api/webapi.py @@ -644,7 +644,7 @@ def load( After the simulation is complete, you can load the results into a :class:`.SimulationData` object by its ``task_id`` using: - .. code-block:: python py + .. code-block:: python sim_data = web.load(task_id, path="outt/sim.hdf5", verbose=verbose) diff --git a/tidy3d/web/cli/develop/documentation.py b/tidy3d/web/cli/develop/documentation.py index 69fb1d9715..fc3fc9d5e8 100644 --- a/tidy3d/web/cli/develop/documentation.py +++ b/tidy3d/web/cli/develop/documentation.py @@ -174,7 +174,9 @@ def build_documentation(args=None): Additional arguments for the documentation build process. """ # Runs the documentation build from the poetry environment - echo_and_check_subprocess(["poetry", "run", "python", "-m", "sphinx", "docs/", "_docs/"]) + echo_and_check_subprocess( + ["poetry", "run", "python", "-m", "sphinx", "-j", "auto", "docs/", "_docs/"] + ) return 0 diff --git a/tidy3d/web/core/task_info.py b/tidy3d/web/core/task_info.py index d3196be767..f33093b392 100644 --- a/tidy3d/web/core/task_info.py +++ b/tidy3d/web/core/task_info.py @@ -1,4 +1,4 @@ -"""Defnes information about a task""" +"""Defines information about a task""" from abc import ABC from datetime import datetime @@ -12,77 +12,156 @@ class TaskStatus(Enum): """The statuses that the task can be in.""" INIT = "initialized" + """The task has been initialized.""" + QUEUE = "queued" + """The task is in the queue.""" + PRE = "preprocessing" + """The task is in the preprocessing stage.""" + RUN = "running" + """The task is running.""" + POST = "postprocessing" + """The task is in the postprocessing stage.""" + SUCCESS = "success" + """The task has completed successfully.""" + ERROR = "error" + """The task has completed with an error.""" class TaskBase(pydantic.BaseModel, ABC): - """Base config for all task objects.""" + """Base configuration for all task objects.""" class Config: - """configure class""" + """Configuration for TaskBase""" arbitrary_types_allowed = True + """Allow arbitrary types to be used within the model.""" class ChargeType(str, Enum): - """The payment method of task.""" + """The payment method of the task.""" FREE = "free" + """No payment required.""" + PAID = "paid" + """Payment required.""" class TaskBlockInfo(TaskBase): - """The block info that task will be blocked by all three features of DE, - User limit and Insufficient balance""" + """Information about the task's block status. + + This includes details about how the task can be blocked by various features + such as user limits and insufficient balance. + """ chargeType: ChargeType = None + """The type of charge applicable to the task (free or paid).""" + maxFreeCount: int = None + """The maximum number of free tasks allowed.""" + maxGridPoints: int = None + """The maximum number of grid points permitted.""" + maxTimeSteps: int = None + """The maximum number of time steps allowed.""" class TaskInfo(TaskBase): - """General information about task.""" + """General information about a task.""" taskId: str + """Unique identifier for the task.""" + taskName: str = None + """Name of the task.""" + nodeSize: int = None + """Size of the node allocated for the task.""" + completedAt: Optional[datetime] = None + """Timestamp when the task was completed.""" + status: str = None + """Current status of the task.""" + realCost: float = None + """Actual cost incurred by the task.""" + timeSteps: int = None + """Number of time steps involved in the task.""" + solverVersion: str = None + """Version of the solver used for the task.""" + createAt: Optional[datetime] = None + """Timestamp when the task was created.""" + estCostMin: float = None + """Estimated minimum cost for the task.""" + estCostMax: float = None + """Estimated maximum cost for the task.""" + realFlexUnit: float = None + """Actual flexible units used by the task.""" + oriRealFlexUnit: float = None + """Original real flexible units.""" + estFlexUnit: float = None + """Estimated flexible units for the task.""" + estFlexCreditTimeStepping: float = None + """Estimated flexible credits for time stepping.""" + estFlexCreditPostProcess: float = None + """Estimated flexible credits for post-processing.""" + estFlexCreditMode: float = None + """Estimated flexible credits based on the mode.""" + s3Storage: float = None + """Amount of S3 storage used by the task.""" + startSolverTime: Optional[datetime] = None + """Timestamp when the solver started.""" + finishSolverTime: Optional[datetime] = None + """Timestamp when the solver finished.""" + totalSolverTime: int = None + """Total time taken by the solver.""" + callbackUrl: str = None + """Callback URL for task notifications.""" + taskType: str = None + """Type of the task.""" + metadataStatus: str = None + """Status of the metadata for the task.""" + taskBlockInfo: TaskBlockInfo = None + """Blocking information for the task.""" class RunInfo(TaskBase): - """Information about the run.""" + """Information about the run of a task.""" perc_done: pydantic.confloat(ge=0.0, le=100.0) + """Percentage of the task that is completed (0 to 100).""" + field_decay: pydantic.confloat(ge=0.0, le=1.0) + """Field decay from the maximum value (0 to 1).""" def display(self): - """Print some info.""" + """Print some info about the task's progress.""" print(f" - {self.perc_done:.2f} (%) done") print(f" - {self.field_decay:.2e} field decay from max")