Add basic demo back in

Author: znicholls

docs/NAVIGATION.md

@@ -6,6 +6,7 @@ See https://oprypin.github.io/mkdocs-literate-nav/
 - [Home](index.md)
 - [Installation](installation.md)
 - [How-to guides](how-to-guides/index.md)
+    - [Basic demo](how-to-guides/basic-demo.py)
 - [Tutorials](tutorials/index.md)
 - [Further background](further-background/index.md)
     - [Dependency pinning and testing](further-background/dependency-pinning-and-testing.md)

docs/how-to-guides/basic-demo.py

@@ -0,0 +1,82 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.17.2
+#   kernelspec:
+#     display_name: Python 3 (ipykernel)
+#     language: python
+#     name: python3
+# ---
+
+# %% [markdown]
+# # Basic demo
+#
+# Here we show a very basic demo of how to use the package.
+# The actual behaviour isn't so interesting,
+# but it demonstrates that we can wrap code
+# that is ultimately written in Fortran.
+
+# %% [markdown]
+# ## Imports
+
+# %%
+import pint
+
+from example_fgen_basic.error_v import ErrorV
+from example_fgen_basic.error_v.creation import create_error, create_errors
+from example_fgen_basic.error_v.passing import pass_error, pass_errors
+from example_fgen_basic.get_wavelength import get_wavelength, get_wavelength_plain
+
+# %% [markdown]
+# ## Calculation with basic types
+#
+# Here we show how we can use a basic wrapped function.
+# This functionality isn't actually specific to our wrappers
+# (you can do the same with f2py),
+# but it's a useful starting demonstration.
+
+# %%
+# `_plain` because this works on plain floats,
+# not quantities with units (see below for this demonstration)
+get_wavelength_plain(400.0e12)
+
+# %% [markdown]
+# With these python wrappers,
+# we can also do nice things like support interfaces that use units
+# (this would be much more work to implement directly in Fortran).
+
+# %%
+ur = pint.get_application_registry()
+
+# %%
+get_wavelength(ur.Quantity(400.0, "THz")).to("nm")
+
+# %% [markdown]
+# ## Receiving and passing derived types
+#
+# TODO: more docs and cross-references on how this actually works
+
+# %% [markdown]
+# We can receive a Python-equivalent of a Fortran derived type.
+
+# %%
+create_error(3)
+
+# %% [markdown]
+# Or multiple derived types.
+
+# %%
+create_errors([1, 2, 1, 5])
+
+# %% [markdown]
+# We can also pass Python-equivalent of Fortran derived types back into Fortran.
+
+# %%
+pass_error(ErrorV(code=0))
+
+# %%
+pass_errors([ErrorV(code=0), ErrorV(code=3), ErrorV(code=5), ErrorV(code=-2)])

pyproject.toml

@@ -94,6 +94,7 @@ docs = [
     "jupyterlab>=4.4.5",
     "jupytext>=1.17.2",
     "mkdocs-jupyter>=0.25.1",
+    "pint>=0.24.4",
 ]
 # For minimum test dependencies.
 # These are used when running our minimum PyPI install tests.

requirements-docs-locked.txt

@@ -28,6 +28,8 @@ defusedxml==0.7.1
 exceptiongroup==1.3.0 ; python_full_version < '3.11'
 executing==2.1.0
 fastjsonschema==2.21.1
+flexcache==0.3
+flexparser==0.4
 fonttools==4.59.0
 ford==6.1.13
 fqdn==1.5.1
@@ -103,6 +105,7 @@ parso==0.8.4
 pathspec==0.12.1
 pexpect==4.9.0 ; (python_full_version < '3.10' and sys_platform == 'emscripten') or (sys_platform != 'emscripten' and sys_platform != 'win32')
 pillow==11.3.0
+pint==0.24.4
 platformdirs==4.3.6
 prometheus-client==0.21.1
 prompt-toolkit==3.0.48

src/example_fgen_basic/error_v/error_v.py

@@ -60,3 +60,21 @@ def from_instance_index(cls, instance_index: int) -> ErrorV:
         res = cls(code=code, message=message)
 
         return res
+
+    def build_fortran_instance(self) -> int:
+        """
+        Build an instance equivalent to `self` on the Fortran side
+
+        Intended for use mainly by wrapping functions.
+        Most users should not need to use this method directly.
+
+        Returns
+        -------
+        :
+            Instance index of the object which has been created on the Fortran side
+        """
+        instance_index: int = m_error_v_w.build_instance(
+            code=self.code, message=self.message
+        )
+
+        return instance_index

src/example_fgen_basic/error_v/passing.py

@@ -48,7 +48,7 @@ def pass_error(inv: ErrorV) -> bool:
         If `inv` is an error, `True`, otherwise `False`.
     """
     # Tell Fortran to build the object on the Fortran side
-    instance_index: int = m_error_v_w.build_instance(code=inv.code, message=inv.message)
+    instance_index = inv.build_fortran_instance()
 
     # Call the Fortran function
     # Boolean wrapping strategy, have to cast to bool