Getting started tutorial

[TianHengZhuang]

Description

Add a "Getting Started" tutorial page and Jupyter notebook that walk new users through a first steady horseshoe vortex lattice method (VLM) simulation from scratch.

Motivation

New users currently have to piece together the object model from the API reference and the example scripts. A step-by-step tutorial lowers the barrier to entry, gives a concrete starting point for exploring the library, and makes Ptera Software easier to evaluate and adopt.

Relevant Issues

None.

Changes

• Add tutorials/getting_started.ipynb, a runnable notebook that builds an Airfoil, WingCrossSection, Wing, Airplane, and OperatingPoint, runs a steady VLM simulation with SteadyHorseshoeVortexLatticeMethodSolver, and covers results, visualization, logging, and saving/loading.
• Add docs/website/tutorials/getting_started.md, which embeds the notebook on the documentation site.
• Add the tutorial page to the website toctree before the examples section.
• Add TianHeng Zhuang to the contributors list in the README.

Dependency Updates

None.

Change Magnitude

Minor: Small change such as a bug fix, small enhancement, or documentation update.

Checklist (check each item when completed or not applicable)

• I am familiar with the current contribution guidelines.
• PR description links all relevant issues and follows this template.
• My branch is based on main and is up to date with the upstream main branch.
• All calculations use S.I. units.
• Code is formatted with black (line length = 88).
• Code is well documented with block comments where appropriate.
• Any external code, algorithms, or equations used have been cited in comments or docstrings.
• All new modules, classes, functions, and methods have docstrings in reStructuredText format, and are formatted using docformatter (--in-place --black). See the style guide for type hints and docstrings for more details.
• All new classes, functions, and methods in the pterasoftware package use type hints. See the style guide for type hints and docstrings for more details.
• If any major functionality was added or significantly changed, I have added or updated tests in the tests package.
• Code locally passes all tests in the tests package.
• This PR passes the ReadTheDocs build check (this runs automatically with the other workflows).
• This PR passes the ascii-only, pre-commit-hooks, and zizmor GitHub actions.
• This PR passes the lint job of the CI GitHub action.
• This PR passes the test jobs of the CI GitHub action.

Assisted-by: Marvis (AI assistant)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.39%. Comparing base (cd5b068) to head (9bc3937).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #293   +/-   ##
=======================================
  Coverage   94.39%   94.39%           
=======================================
  Files          47       47           
  Lines        9686     9686           
=======================================
  Hits         9143     9143           
  Misses        543      543           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[camUrban]

Thanks so much for your work @TianHengZhuang! This looks like a great start. Could you commit changes with the following fixes, and then re-request a review? Before you re-request a review, you should also mark each comment as resolved.

Also, as you are a new contributor, be sure to add your name to the bottom of the list of contributors in the README.md file. Us one of the pre-existing patterns for formatting.

Lastly, would you mind revising your PR's description to follow .github/pull_request_template.md? That really helps keep everything organized.

[camUrban]

One more thing I forgot to mention: it looks like the lint CI action and two of the pre-commit-hooks actions are failing. This likely means you don't have pre-commit installed yet, as that would have prevented you from committing. The easiest way to get it set up is to follow the steps in CONTRIBUTING.md. Those hooks should check for issues and automatically adjust formatting to align your changes with the project's style. 😃

[TianHengZhuang]

Hi @camUrban, thanks for the thorough review! I've addressed all the inline comments and pushed the fixes:

• R3: Removed hard line wrapping in docs/website/tutorials/getting_started.md.
• R7: Moved the literalinclude block to the end of the file.
• R18: Removed the duplicate install step.
• R23: Removed the redundant list item.
• R32: Fixed the class structure wording in the notebook.
• R9: Moved the tutorials section before examples in docs/website/README.md.
• R19: Used the actual solver class name (SteadyHorseshoeVortexLatticeMethodSolver) and added a step 8 for saving/loading results.
• R523: Removed images and execution metadata from the notebook.

Also:

• Added TianHeng Zhuang (TianHengZhuang) to the README contributors list.
• Rewrote the PR description to follow the pull request template.
• Ran codespell, black, end-of-files, mixed-line-endings, and ascii-only checks locally - all pass.
• Changed the ipynb lexer to json in conf.py to fix the RTD build warning.

Could you please take another look when you have a moment? Re-requesting review now. Thanks!

[TianHengZhuang]

Just pushed a small fix: restored docs/website/tutorials.md with LF line endings (it was accidentally removed in a prior commit). The lint CI / pre-commit workflows are currently waiting for approval (action_required) before they can run — could you approve them so the checks re-run? Thanks!

[camUrban]

Hey @TianHengZhuang! I'm about to post specific review comments, but decided to first push a change to your branch, which changes how the notebook is rendered and adds a script that stores its outputs. Please pull before editing. The workflow for any notebook change is now: edit, run python scripts/execute_tutorials.py, then commit the notebook and any file it wrote. The script needs the packages in requirements_dev.txt.

[camUrban]

Accidentally approved: see comment below. The line-by-line comments I'd like changed are still accurate.

[camUrban]

Hi @TianHengZhuang. Here are my final comments. Great work again 😃

Could you mark each comment as "resolved" once you've completed it? After they are all resolved, feel free to request a final review.

Also, apologies for accidentally approving this before. I meant to click "Request changes". My bad 😆

[camUrban]

By the way, don't worry about the Read the Docs check showing as failed. The build didn't get past fetching the SciPy intersphinx inventory because docs.scipy.org is shakey at the moment. It will pass once SciPy's docs are back and the build is retried.

In the meantime, please check the site locally after each change. From the repository root, with your virtual environment active:

pip install -r docs/website/requirements_docs.txt
sphinx-build -W --keep-going -b html docs/website docs/website/_build/html

Then open docs/website/_build/html/tutorials/getting_started.html in a browser. The -W flag matches the Read the Docs configuration, so a clean local build means the hosted one will pass too. While docs.scipy.org is down, the local build fails with the same intersphinx warning, so if that is the only warning in the output, your changes are fine.

[TianHengZhuang]

Thanks for the review, @camUrban! I've pushed a new commit that addresses all documentation comments:

• Reordered sections in getting_started.md so the notebook appears at the end
• Removed the redundant solvers list paragraph that duplicated the notebook content
• Unwrapped hard-wrapped paragraphs in both getting_started.md and utorials.md
• Moved tutorials before examples in the docs toctree

The notebook content fixes from the previous commit are also in place. Ready for your review whenever you have time!

[TianHengZhuang]

Thanks for the detailed review! I've pushed a new commit (2d7966f) addressing all the documentation comments in docs/website/tutorials/getting_started.md, docs/website/tutorials.md, and docs/website/README.md, plus the inline notebook fixes in the previous commit (c593da9).

Since the inline review comments can only be marked as resolved by the comment author via the GitHub UI, could you mark each one as resolved when you have a moment, or simply approve the PR if everything looks good? Either way works for me - I just want to make sure I'm not missing anything.

[camUrban]

Hi @TianHengZhuang. Thanks for taking the time to look over my comments. Unfortunately, it looks like you force-pushed over my changes. Thankfully, I still had a local copy, so I was able to re-push them (with your edits merged in).

Important

Please don't force push unless you are certain why a push is failing. If git push ever fails unexpectedly, never git push --force, as that often deletes someone else's work.

Instead, get in the habit of running git pull before you make changes. Then, after you make your edits, git commit and git push. No worries, it happens, but just something to keep in mind going forward.

Review Comments

Thanks for letting me know that you can't resolve comments. I didn't know that!

I've resolved the comments that you fixed. However, there are still eight that need to be taken care of. Let me know if you have any further questions. And, one last reminder, please git pull before you start! 😊

Editing the Notebook

The notebook is now rendered on the documentation site from the outputs stored in the file, so there are a couple of extra steps after editing it:

1. Edit the notebook however you like, in Jupyter or a text editor. Don't worry about outputs or execution counts, since the next step regenerates them.

2. Run the execution script from the repository root with your virtual environment active:

   pip install -r requirements.txt -r requirements_dev.txt
   python scripts/execute_tutorials.py

   It runs the notebook top to bottom, stores the outputs, and strips the metadata that shouldn't be committed. If it reports a failure, fix the cell it names and run it again.

3. Commit tutorials/getting_started.ipynb together with any file the notebook writes next to itself, such as the WebP render. The *.psz file is gitignored and stays out.

   One rule the script enforces: images are saved to files and embedded from markdown cells, never displayed inline. An inline image would be stored as base64 text in the notebook, and the script refuses to write that.

Checking Your Work on the RTD Website

Every push builds a preview of the documentation site. Click on the "docs/readthedocs.org:pterasoftware" check at the bottom of this PR, and open Tutorials in the sidebar. That is exactly what readers will see, rendered from your stored outputs, so it's the best way to check a change. You can also build it locally:

pip install -r docs/website/requirements_docs.txt
sphinx-build -W --keep-going -b html docs/website docs/website/_build/html

and open docs/website/_build/html/tutorials/getting_started.html.