FEAT: Latest git submodule testing 🍰

daquinteroflex · daquinteroflex · commit 9419bd015133 · 2024-02-13T11:22:18.000+01:00
diff --git a/.github/workflows/run_tests.yml b/.github/workflows/run_tests.yml
@@ -18,11 +18,79 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: "3.10"
+          submodules: 'recursive'
       - name: Test pre-commit hooks
         run: |
           python -m pip install --upgrade pip
           pip install pre-commit
           pre-commit run
+  test-latest-submodules:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository with submodules
+        uses: actions/checkout@v3
+        with:
+          submodules: 'recursive'
+          # This fetches only a single branch by default, so additional fetch is needed
+          fetch-depth: 0 # Optionally, set to 0 to fetch all history for all branches and tags
+
+      - name: Determine current branch or PR ref
+        id: get_branch
+        run: |
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            echo "BRANCH_NAME=${{ github.event.pull_request.base.ref }}" >> $GITHUB_ENV
+          else
+            echo "BRANCH_NAME=$(echo $GITHUB_REF | sed 's|refs/heads/||')" >> $GITHUB_ENV
+          fi
+          echo $BRANCH_NAME
+        shell: bash
+
+      - name: Initialize and update submodule
+        run: |
+          git submodule update --init --recursive
+
+      - name: Check if submodules are up to date
+        shell: bash
+        run: |
+          NOTEBOOKS_PATH=docs/notebooks
+          FAQ_PATH=docs/faq
+
+          # Checking out Notebooks submodule with the same branch as the main project
+          echo "Checking $NOTEBOOKS_PATH for updates..."
+          cd $NOTEBOOKS_PATH
+          echo $(git fetch --all --verbose)
+          echo $(git remote get-url origin)
+          git checkout origin/$BRANCH_NAME
+          if git show-ref --verify refs/remotes/origin/$BRANCH_NAME; then
+           echo "Branch $BRANCH_NAME exists."
+          else
+            echo "::error::Branch $BRANCH_NAME does not exist on remote."
+            exit 1
+          fi
+          NOTEBOOKS_LATEST_COMMIT=$(git rev-parse refs/remotes/origin/${{ env.BRANCH_NAME }})
+          NOTEBOOKS_CURRENT_COMMIT=$(git rev-parse HEAD)
+          
+          
+          cd ../..
+          if [ "$NOTEBOOKS_LATEST_COMMIT" != "$NOTEBOOKS_CURRENT_COMMIT" ]; then
+            echo "::error ::Submodule $NOTEBOOKS_PATH is not up to date with the ${{ env.BRANCH_NAME }} branch. Please update it."
+            exit 1
+          else
+            echo "Submodule $NOTEBOOKS_PATH is up to date with the ${{ env.BRANCH_NAME }} branch."
+          fi
+
+          # Checking FAQs only on the develop branch.
+          echo "Checking $FAQ_PATH for updates..."
+          cd $FAQ_PATH
+          FAQ_LATEST_COMMIT=$(git rev-parse origin/develop)
+          FAQ_CURRENT_COMMIT=$(git rev-parse HEAD)
+          cd ../..
+          if [ "$FAQ_LATEST_COMMIT" != "$FAQ_CURRENT_COMMIT" ]; then
+            echo "::error ::Submodule $FAQ_PATH is not up to date. Please update it."
+            exit 1
+          else
+            echo "Submodule $FAQ_PATH is up to date."
+          fi
   build:
     name: test ${{ matrix.python-version }} - ${{ matrix.platform }}
     runs-on: ${{ matrix.platform }}
diff --git a/.github/workflows/sync-to-readthedocs-repo.yaml b/.github/workflows/sync-to-readthedocs-repo.yaml
@@ -80,6 +80,9 @@ jobs:
         uses: actions/checkout@v3
         with:
           submodules: true
+      - id: clean
+        run: |
+          rm -rf .github/ # removes the further triggered github actions.
       - name: Create new branch if version pattern
         uses: GuillaumeFalourd/create-other-repo-branch-action@v1.5
         with:
diff --git a/.gitmodules b/.gitmodules
@@ -1,7 +1,6 @@
 [submodule "docs/notebooks"]
 	path = docs/notebooks
 	url = git@github.com:flexcompute/tidy3d-notebooks.git
-	branch = develop
 [submodule "docs/faq"]
 	path = docs/faq
 	url = https://github.com/flexcompute/tidy3d-faq
diff --git a/README.md b/README.md
@@ -12,17 +12,14 @@ Name](https://img.shields.io/badge/pypi-tidy3d-blue?style=for-the-badge)](https:
 
 ![](https://raw.githubusercontent.com/flexcompute/tidy3d/main/img/Tidy3D-logo.svg)
 
-Tidy3D is a software product from Flexcompute that enables large scale electromagnetic simulation using the finite-difference time-domain (FDTD) method.
+Tidy3D is a software package for solving extremely large electrodynamics problems using the finite-difference time-domain (FDTD) method. It can be controlled through either an [open source python package](https://github.com/flexcompute/tidy3d) or a [web-based graphical user interface](https://tidy3d.simulation.cloud).
 
-This repository stores the python interface for Tidy3d.
+This repository contains the python API to allow you to:
 
-This code allows you to:
 * Programmatically define FDTD simulations.
 * Submit and manage simulations running on Flexcompute's servers.
 * Download and postprocess the results from the simulations.
 
-You can find a detailed documentation and API reference [here](https://docs.flexcompute.com/projects/tidy3d/en/stable/).
-The source code for our documentation is [here](https://github.com/flexcompute-readthedocs/tidy3d-docs).
 
 ![](https://raw.githubusercontent.com/flexcompute/tidy3d/main/img/snippet.png)
 
@@ -34,7 +31,7 @@ Note that while this front end package is open source, to run simulations on Fle
 You can sign up for an account [here](https://tidy3d.simulation.cloud/signup).
 After that, you can install the front end with the instructions below, or visit [this page](https://docs.flexcompute.com/projects/tidy3d/en/stable/install.html) in our documentation for more details.
 
-### Installing the front end 
+### Quickstart Installation
 
 To install the Tidy3D Python API locally, the following instructions should work for most users.
 
@@ -53,124 +50,38 @@ import tidy3d.web as web
 web.configure("XXX")
 ```
 
-If those commands did not work, advanced installation instructions are below, which should help solve the issue.
+**Advanced installation instructions for all platforms is available in the [documentation installation guides](https://docs.flexcompute.com/projects/tidy3d/en/latest/install.html).**
 
-### Advanced Installation Instructions
+### Authentication Verification
 
-Some users might require more a specialized installation, which we cover below.
-
-#### Using pip (recommended)
-
-The easiest way to install the tidy3d python interface is through [pip](https://pypi.org/project/tidy3d/).
-
-```
-pip install tidy3d
-```
-
-This will install the latest stable version.
-
-To get a specific version `x.y.z`, including the "pre-release" versions, you may specify the version in the command as:
-
-```
-pip install tidy3d==x.y.z
-```
-
-### Installing from source
-
-Alternatively, for development purposes, eg. developing your own features, you may download and install the package from source as:
-
-```
-git clone https://github.com/flexcompute/tidy3d.git
-cd tidy3d
-pip install -e .
-```
-
-### Configuring and authentication
-
-With the front end installed, it must now be configured with your account information, which is done via an "API key".
-
-You can find your API key in the [web interface](http://tidy3d.simulation.cloud). After signing in and navigating to the account page by clicking the "Account Center" icon on the left-hand side. Then, click on the "API key" tab on the right hand side of the menu and copy your API key.
-
-Note: We refer to your API specific API key value as `XXX` below.
-
-To link your API key with Tidy3D, you may use one of three following options:
-
-#### Command line (recommended)
-
-The easiest way is through the command line via the `tidy3d configure` command. Run:
-
-```
-tidy3d configure
-```
-
-and then enter your API key `XXX` when prompted.
-
-Note that Windows users must run the following instead (ideally in an anaconda prompt):
-
-```
-pip install pipx
-pipx run tidy3d configure
-```
-
-You can also specify your API key directly as an option to this command using the `api-key` argument, for example:
-
-```
-tidy3d configure --apikey=XXX
-```
-
-#### Manually
-
-Alternatively, you can manually set up the config file where Tidy3D looks for the API key. The API key must be in a file called `.tidy3d/config` located in your home directory, containing the following
+To test the authentication, you may try importing the web interface via.
 
 ```
-apikey = "XXX"
+python -c "import tidy3d; tidy3d.web.test()"
 ```
 
-You can manually set up your file like this, or do it through the command line line:
-
-``echo 'apikey = "XXX"' > ~/.tidy3d/config``
-
-Note the quotes around `XXX`.
-
-Note that Windows users will most likely need to place the `.tidy3d/config` file in their `C:\Users\username\` directory (where `username` is your username).
-
-#### Environment Variable
-
-Lastly, you may set the API key as an environment variable named `SIMCLOUD_APIKEY`.
-
-This can be set up using
-
-``export SIMCLOUD_APIKEY="XXX"``
-
-Note the quotes around `XXX`.
-
-### Testing the installation and authentication
-
-#### Front end package
-
-You can verify the front end installation worked by running:
-
-```
-python -c "import tidy3d as td; print(td.__version__)"
-```
+It should pass without any errors if the API key is set up correctly.
 
-and it should print out the version number, for example:
+To get started, our documentation has a lot of [examples](https://docs.flexcompute.com/projects/tidy3d/en/latest/notebooks/index.html) for inspiration.
 
-```
-2.0.0
-```
+## Common Documentation References
 
-#### Authentication
+| API Resource       | URL                                                                              |
+|--------------------|----------------------------------------------------------------------------------|
+| Installation Guide | https://docs.flexcompute.com/projects/tidy3d/en/latest/install.html              |
+| Documentation      | https://docs.flexcompute.com/projects/tidy3d/en/latest/index.html                |
+| Example Library    | https://docs.flexcompute.com/projects/tidy3d/en/latest/notebooks/docs/index.html |
+| FAQ                | https://docs.flexcompute.com/projects/tidy3d/en/latest/faq/docs/index.html       |
 
-To test the authentication, you may try importing the web interface via.
 
-```
-python -c "import tidy3d.web"
-```
+## Related Source Repositories
 
-It should pass without any errors if the API key is set up correctly.
+| Name              | Repository                                      |
+|-------------------|-------------------------------------------------|
+| Source Code       | https://github.com/flexcompute/tidy3d           |
+| Notebooks Source  | https://github.com/flexcompute/tidy3d-notebooks |
+| FAQ Source Code   | https://github.com/flexcompute/tidy3d-faq       |
 
-To get started, our documentation has a lot of [examples](https://docs.flexcompute.com/projects/tidy3d/en/latest/examples.html) for inspiration.
 
 ## Issues / Feedback / Bug Reporting
 
diff --git a/docs/404.rst b/docs/404.rst
@@ -0,0 +1,14 @@
+.. _404:
+
+404
+===
+
+Oops! You've hit a wavelength that doesn't resonate with our server. Try a different frequency!
+
+If you have arrived here from a link in our pre-v2.6 documentation, we apologize for the inconvenience. We have restructured our documentation to make it more user-friendly and informative, and the page links have changed. We recommend you return to the `homepage <index.html>`_ and navigate to the page you were looking for from there.
+
+Please let us know what happened that got you here by raising a `GitHub issue <https://github.com/flexcompute/tidy3d/issues>`_ if not! We'll do our best to help you out.
+
+.. image:: /_static/img/404.png
+   :alt: 404 - Page not found
+   :align: center
diff --git a/docs/_static/img/404.png b/docs/_static/img/404.png
diff --git a/docs/development/documentation.rst b/docs/development/documentation.rst
@@ -81,3 +81,11 @@ The command can be executed using the ``poetry run`` command. It requires specif
     poetry run tidy3d develop replace-in-files -d ./ -j ./docs/versions/test_replace_in_files.json -v 0.18.0 --dry-run True
 
 This example will process files in the current directory (``./``), using the replacement rules specified in ``test_replace_in_files.json`` for version ``0.18.0``. The ``--dry-run`` flag set to ``True`` ensures that changes are not actually applied, allowing for a safe preview of potential modifications.
+
+
+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.<your_reference>``
+- In notebooks, always have absolute links, otherwise the links will break when the user downloads them.
diff --git a/docs/faq b/docs/faq
@@ -1 +1 @@
-Subproject commit 8f744b320c19418f9870c22dd6c4ef3941896379
+Subproject commit fc45d38162184a8a5d2fae1a3f133123b2dc053e
diff --git a/docs/index.rst b/docs/index.rst
@@ -22,6 +22,15 @@ Tidy3D Electromagnetic Solver
 
 Tidy3D is a software package for solving extremely large electrodynamics problems using the finite-difference time-domain (FDTD) method. It can be controlled through either an `open source python package <https://github.com/flexcompute/tidy3d>`_ or a `web-based graphical user interface <https://tidy3d.simulation.cloud>`_.
 
+This python API allows you to:
+
+* Programmatically define FDTD simulations.
+* Submit and manage simulations running on Flexcompute's servers.
+* Download and postprocess the results from the simulations.
+
+
+
+
 Get Started
 ===========
 
diff --git a/docs/notebooks b/docs/notebooks
@@ -1 +1 @@
-Subproject commit c9a4af80c112221c9f042f158276c3cc8067239d
+Subproject commit 61c1691d846ffa95e78a1c7c17cb373013f99c21
diff --git a/tidy3d/constants.py b/tidy3d/constants.py
@@ -14,14 +14,40 @@
 
 # fundamental constants (https://physics.nist.gov)
 C_0 = 2.99792458e14
+"""
+Speed of light in vacuum [um/s]
+"""
+
 MU_0 = 1.25663706212e-12
+"""
+Vacuum permeability [H/um]
+"""
+
 EPSILON_0 = 1 / (MU_0 * C_0**2)
+"""
+Vacuum permittivity [F/um]
+"""
 
 #: Free space impedance
 ETA_0 = np.sqrt(MU_0 / EPSILON_0)
+"""
+Vacuum impedance in Ohms
+"""
+
 Q_e = 1.602176634e-19
+"""
+Fundamental charge [C]
+"""
+
 HBAR = 6.582119569e-16
+"""
+Reduced Planck constant [eV*s]
+"""
+
 K_B = 8.617333262e-5
+"""
+Boltzmann constant [eV/K]
+"""
 
 # floating point precisions
 dp_eps = np.finfo(np.float64).eps
