Add Read the Docs integration

.gitignore

@@ -40,6 +40,7 @@ venv/
 build/
 build-*/
 build_test/
+doc/_build/
 
 CMakeUserPresets.json
 CMakeSettings.json

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: doc/conf.py
+
+python:
+  install:
+    - requirements: doc/requirements.txt

doc/Makefile

@@ -0,0 +1,11 @@
+SPHINXBUILD ?= python3 -m sphinx
+SOURCEDIR = .
+BUILDDIR = _build
+
+.PHONY: help Makefile
+
+help:
+	$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)"
+
+%: Makefile
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)"

doc/architecture.md

@@ -0,0 +1,32 @@
+# Architecture
+
+The project builds a layered Fortran solver with optional parser, output, conformal, and MTLN components. CMake assembles these layers into static libraries and links them into the final `semba-fdtd` executable.
+
+## Entry point and execution flow
+
+- `src_main_pub/launcher.F90` defines the executable entry point.
+- The launcher creates a `semba_fdtd_t` instance and calls `init()`, `launch()`, and `end()`.
+- `src_main_pub/semba_fdtd.F90` owns high-level solver setup, input parsing, runtime flags, and orchestration.
+- `src_main_pub/timestepping.F90` defines the `solver_t` type and the main stepping operations that advance fields, sources, boundaries, outputs, and optional MTLN behavior.
+
+## Main code areas
+
+- `src_main_pub/`: solver control flow, field stepping, observations, VTK/XDMF output, MPI communication.
+- `src_json_parser/`: FDTD JSON parser and related labels/types.
+- `src_mtln/`: multiconductor transmission-line solver and ngspice integration points.
+- `src_conformal/`: conformal geometry support.
+- `src_wires_pub/`: wire models and MTLN wire coupling.
+
+## Build composition
+
+At the CMake level, the main libraries are organized around:
+
+- `semba-types`
+- `semba-reports`
+- `smbjson` when JSON input is enabled
+- `mtlnsolver` and `ngspice_interface` when MTLN is enabled
+- `conformal`
+- `semba-components`
+- `semba-outputs`
+
+Those pieces are linked into the final executable and, when enabled, the test binaries.

doc/cli-reference.md

@@ -0,0 +1,25 @@
+# Command-line reference
+
+The primary command-line entry point is the `semba-fdtd` executable generated by the build.
+
+## Basic invocation
+
+```bash
+semba-fdtd -i CASE_NAME.fdtd.json
+```
+
+When building from source in the default layout, the executable is located at:
+
+```text
+build/bin/semba-fdtd
+```
+
+## Inputs
+
+- `-i CASE_NAME.fdtd.json`: pass the case file to run.
+
+## Related configuration
+
+The `.fdtd.json` input format also supports `general.additionalArguments`, which can forward solver flags from the input file when needed. Console arguments still take precedence.
+
+See [](fdtdjson.md) for the data model used by the input file.

doc/conf.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+project = "semba-fdtd"
+author = "OpenSEMBA"
+copyright = "OpenSEMBA"
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.githubpages",
+]
+
+source_suffix = {
+    ".md": "markdown",
+}
+
+root_doc = "index"
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "templates",
+]
+
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_image",
+]
+myst_heading_anchors = 3
+
+html_theme = "sphinx_rtd_theme"
+html_title = "semba-fdtd documentation"
+html_static_path: list[str] = []
+html_theme_options = {
+    "collapse_navigation": False,
+    "navigation_depth": 4,
+}
+html_context = {
+    "display_github": True,
+    "github_user": "OpenSEMBA",
+    "github_repo": "fdtd",
+    "github_version": "main",
+    "conf_py_path": "/doc/",
+}

doc/contributing.md

@@ -0,0 +1,28 @@
+# Contributing
+
+This page summarizes the repository contribution workflow. The authoritative source is the top-level `CONTRIBUTING.md`, but the key expectations are collected here for easier navigation inside the docs site.
+
+## Basic workflow
+
+1. Fork the repository.
+2. Clone your fork.
+3. Initialize and update submodules.
+4. Create a feature branch from the active development branch.
+5. Open a pull request once the change is documented and tested.
+
+## Expectations for changes
+
+- Keep changes focused.
+- Follow the surrounding Fortran and Python style.
+- Update documentation when behavior or public interfaces change.
+- Add or update tests when new functionality is introduced.
+
+## Before opening a pull request
+
+- Build the project with CMake.
+- Run the relevant compiled tests and Python tests.
+- Explain the motivation, scope, and validation of the change in the PR description.
+
+## Review policy
+
+Pull requests are expected to be reviewed and approved before merge. The repository also requires extra human review for significant AI-generated contributions, as described in the root contribution guide.

doc/developer-guide.md

@@ -0,0 +1,12 @@
+# Developer guide
+
+This section collects the material needed to build, test, debug, and extend the solver.
+
+```{toctree}
+:maxdepth: 2
+
+architecture
+development
+testing
+contributing
+```

doc/development.md

@@ -23,7 +23,7 @@ If you use intel oneapi compiler, make sure to run
 
 #### HDF5 Libraries
 
-HDF5 precompiled libraries for ubuntu are used by default (see [precompiled libraries cmake script](../set_precompiled_libraries.cmake)).  
+HDF5 precompiled libraries for ubuntu are used by default (see [precompiled libraries CMake script](https://github.com/OpenSEMBA/fdtd/blob/main/set_precompiled_libraries.cmake)).  
 
 You can compile HDF5 for your specific platform downloading the latest sources from this [link](https://www.hdfgroup.org/downloads/hdf5/source-code/).
 Extract to a folder and build and install with the following commands
@@ -392,4 +392,4 @@ Run the following command as super user:
 ```
 echo 0| sudo tee /proc/sys/kernel/yama/ptrace_scope 
 ```
-([source](https://github.com/Microsoft/MIEngine/wiki/Troubleshoot-attaching-to-processes-using-GDB))
+([source](https://github.com/Microsoft/MIEngine/wiki/Troubleshoot-attaching-to-processes-using-GDB))

doc/fdtdjson.md

@@ -7,11 +7,11 @@ This document assumes that you are familiar with the basic JSON notation, a brie
 
 The following are examples of valid inputs:
 
- 1. An empty space illuminated by a plane wave: [planewave.fdtd.json](testData/input_examples/planewave.fdtd.json). The field at a point close to the center is recorded.
- 2. A thin straight wire illuminated by a plane wave: [holland1981.fdtd.json](testData/input_examples/holland1981.fdtd.json) which aims to replicate the case described in https://doi.org/10.1109/TEMC.1981.303899. It contains a probe which records the wire at the middle of the wire.
- 3. A current injection which mimics a lightning strike on a square metallic surface: [currentinjection.fdtd.json](testData/input_examples/currentInjection.fdtd.json). It contains two bulk current probes to measure the current at the entry and exit lines.
- 4. A shielded pair of wires fed by a voltage source in one of its ends: [shieldedPair.fdtd.json](testData/input_examples/shieldedPair.fdtd.json). The interior of the shield uses a multiconductor transmission line (MTL) algorithm to evolve the common mode currents which are induced in the shield and propagated inside using a transfer impedance.
- 5. A multiconductor transmission line network (MTLN) case which includes three cable bundles with a shared junction: [mtln.fdtd.json](testData/input_examples/mtln.fdtd.json).
+ 1. An empty space illuminated by a plane wave: [planewave.fdtd.json](https://github.com/OpenSEMBA/fdtd/blob/main/testData/input_examples/planewave.fdtd.json). The field at a point close to the center is recorded.
+ 2. A thin straight wire illuminated by a plane wave: [holland1981.fdtd.json](https://github.com/OpenSEMBA/fdtd/blob/main/testData/input_examples/holland1981.fdtd.json) which aims to replicate the case described in https://doi.org/10.1109/TEMC.1981.303899. It contains a probe which records the wire at the middle of the wire.
+ 3. A current injection which mimics a lightning strike on a square metallic surface: [currentInjection.fdtd.json](https://github.com/OpenSEMBA/fdtd/blob/main/testData/input_examples/currentInjection.fdtd.json). It contains two bulk current probes to measure the current at the entry and exit lines.
+ 4. A shielded pair of wires fed by a voltage source in one of its ends: [shieldedPair.fdtd.json](https://github.com/OpenSEMBA/fdtd/blob/main/testData/input_examples/shieldedPair.fdtd.json). The interior of the shield uses a multiconductor transmission line (MTL) algorithm to evolve the common mode currents which are induced in the shield and propagated inside using a transfer impedance.
+ 5. A multiconductor transmission line network (MTLN) case which includes three cable bundles with a shared junction: [mtln.fdtd.json](https://github.com/OpenSEMBA/fdtd/blob/main/testData/input_examples/mtln.fdtd.json).
 
 ## FDTD-JSON objects description
 All units are assumed to be SI-MKS, except when specified otherwise.
@@ -50,8 +50,8 @@ Additionally, it may contain the following optional entry:
 ### `[background]`
 This object sets the background electromagnetic media properties to an specified value it can contain the following objects entries:
 
-+ `[absolutePermittivity]`: a real number indicating the value of background permittivity. Defaults to the value specified in EPSILON_VACUUM at [fdtypes.F90](../src_main_pub/fdetypes.F90).
-+ `[absolutePermeability]`: a real number indicating the value of background permeability. Defaults to the value specified in MU_VACUUM at [fdtypes.F90](../src_main_pub/fdetypes.F90).
++ `[absolutePermittivity]`: a real number indicating the value of background permittivity. Defaults to the value specified in EPSILON_VACUUM at [fdetypes.F90](https://github.com/OpenSEMBA/fdtd/blob/main/src_main_pub/fdetypes.F90).
++ `[absolutePermeability]`: a real number indicating the value of background permeability. Defaults to the value specified in MU_VACUUM at [fdetypes.F90](https://github.com/OpenSEMBA/fdtd/blob/main/src_main_pub/fdetypes.F90).
 
 ### `[boundary]`
 This specifies the boundaries which will be used to terminate the computational domain. 
@@ -90,7 +90,7 @@ These objects must contain a `<type>` label which can be:
 
 All the geometrical information of the simulation case is exclusively stored by the `mesh` object. It is a JSON object which contains three objects: a `<grid>`, a list of `[coordinates]` and a list of `[elements]`.
 
-```json
+```text
 "mesh": {
     "grid": { ... },       
     "coordinates": [ ... ],
@@ -147,7 +147,7 @@ The `elements` entry contains an array of JSON objects, each of which represents
 
   + `node`, representing a point in space. Elements with this type include a `<coordinateIds>` entry which is an array of a single integer representing the `id` of a coordinate and which must exist in the within the `mesh` `coordinates` list.
   + `polyline`, representing an oriented collection of segments. It must contain a list `<coordinateIds>` with at least two coordinates.
-  + `cell`, containing a list of one or more `<intervals>` defined following the [interval convention](#the-interval-convention).
+  + `cell`, containing a list of one or more `<intervals>` defined following the [interval convention](#interval-convention).
   + + If `cell` represents a conformal element it will contain a list of zero or more <intervals> and a list of <triangles>,  describing a close outwards-pointing surface. 
   + + In this case, the `cell` must contain an entry `subtype`, which can be `surface` or `volume`, according to the dimension of the geometrical entity.
 
@@ -175,6 +175,7 @@ Below there is an example of a mesh object which includes several types of eleme
 }
 ```
 
+(interval-convention)=
 ##### The `interval` convention
 
 A `interval` is defined by a pair of two triplets of integer numbers $\mathbf{a} = \{a_x, a_y, a_z\}$ and $\mathbf{b} = \{b_x, b_y, b_z\}$. Each of these triplets refers to a cell and the combination of the two represents a region formed by the closed-open intervals $[a_x, b_x) \times [a_y, b_y) \times [a_z, b_z)$.
@@ -376,6 +377,7 @@ Materials of this type must contain:
 ```
 
 
+(shieldedmultiwire)=
 ### `shieldedMultiwire`
 
 A `shieldedMultiwire`, models $N+1$ electrical wires inside a bundled. The voltages and currents on these wires are solved by a multiconductor transmission lines (MTLN) solver described in:
@@ -418,6 +420,7 @@ They must contain the following entries:
 }
 ```
 
+(unshieldedmultiwire)=
 ### `unshieldedMultiwire`
 
 A `unshieldedMultiwire`, models a bundle of $N$ electrical wires. The charges and currents on these wires are solved using the model described in:
@@ -433,6 +436,7 @@ They must contain the following entries:
         - Two arrays, `<electric>` and `<magnetic>` in which each contain a [field reconstruction object](#field-reconstruction) described below. They must contain a $N$ multipolar expansions, one for each conductor. Each entry assumes that the $n$-th conductor has a prescribed potential of $1 \, \text{V}$ and the rest are floating.
 + `[resistancePerMeter]` and `[conductancePerMeter]` which must be arrays of size $N$. Defaults to zero. If the number of wires is equal to $1$, must be an array of size $1$, e.g. `[50]`.
 
+(field-reconstruction)=
 #### Field reconstruction
 
 The field reconstruction objects contains information necessary to calculate the in-cell parameters for an `unshieldedMultiwire` with $N$ conductors. The `electric` and `magnetic`potentials are used to compute the in-cell capacitances and in-cell inductances, respectively. Each contains information to perform a multipolar expansion based on
@@ -528,7 +532,7 @@ In this case, the three wires of a e-conductor cable are connected to the nodes
 The `connector` represents the physical connection of a bundle to a structure. `connector` assigns properties to the initial or last segment of a `wire`, a `shieldedMultiwire` or an `unshieldedMultiwire`. The `connector` can have the following properties:
 
 + `[resistances]`, an array of real numbers which will be converted to resistances per unit length and will replace the resistancePerMeter of that segment.
-+ `[transferImpedancesPerMeter]`, an array of [transferImpedancePerMeter], as described in the [shieldedMultiwire](#shieldedMultiwire) section. 
++ `[transferImpedancesPerMeter]`, an array of [transferImpedancePerMeter], as described in the [shieldedMultiwire](#shieldedmultiwire) section. 
 
 The most common situation will be having the connector of a shielded bundle. In that case, the arrays have a single component. However, the `connector` can describe the connections of a (unshielded) bundle of $N$ shielded conductors. In that case, the `connector` has to describe the connections, if any, of the $N$ shielded conductors.
 
@@ -572,7 +576,7 @@ Associations with cables can contain the following inputs:
 
 + `<initialTerminalId>` and `<endTerminalId>` which must be present within the `materials` list of type. These entries indicate the lumped circuits connected at the ends of the cable.
 + `[initialConnectorId]` and `[endConnectorId]` entries which must point to materials of type `connector` and are assigned to the last segments of the corresponding ends of the cable.
-+ Its `materialId` must point to a [`wire`](#wire), a [`shieldedMultiwire`](#shieldedMultiwire) or an [`unshieldedMultiwire`](#unshieldedMultiwire) material. If it points to a `shieldedMultiwire`, it must also contain an entry named `<containedWithinElementId>` which indicates the `polyline` in which this `shieldedMultiwire` is embedded.
++ Its `materialId` must point to a [`wire`](#wire), a [`shieldedMultiwire`](#shieldedmultiwire) or an [`unshieldedMultiwire`](#unshieldedmultiwire) material. If it points to a `shieldedMultiwire`, it must also contain an entry named `<containedWithinElementId>` which indicates the `polyline` in which this `shieldedMultiwire` is embedded.
 
 **Example:**
 
@@ -764,7 +768,7 @@ Additionally, a `domain` can contain a `[magnitudeFile]` as specified in [source
 
 This entry is an array which stores all the electromagnetic sources of the simulation case. Each source is a JSON object which must contain the following entries:
 
-+ `<magnitudeFile>` contains a relative path to the plain text file which will be used as a magnitude for this source. This file must contain two columns, with the first stating the time and the second one the magnitude value; an example magnitude file can be found at [gauss.exc](testData/excitations/gauss.exc).
++ `<magnitudeFile>` contains a relative path to the plain text file which will be used as a magnitude for this source. This file must contain two columns, with the first stating the time and the second one the magnitude value; an example magnitude file can be found at [gauss.exc](https://github.com/OpenSEMBA/fdtd/blob/main/testData/excitations/gauss.exc).
 + `<type>` must be a label of the ones defined below. Some examples of source `type` are `planewave` or `nodalSource`.
 + `<elementIds>` is an array of integers which must exist within the `mesh` `elements` list. These indicate the geometrical place where this source is located. The `type` and number of the allowed elements depends on the source `type` and can be check in the descriptions of each source object, below.
 

doc/getting-started.md

@@ -0,0 +1,44 @@
+# Getting started
+
+This page is the shortest path from clone to first simulation. For platform-specific details and debugging workflows, continue to [](development.md).
+
+## Option 1: use a prebuilt release
+
+Prebuilt binaries are published on the project's GitHub releases page:
+
+- <https://github.com/OpenSEMBA/fdtd/releases>
+
+On Windows, the runtime still depends on Intel oneAPI runtime libraries, as described in [](development.md).
+
+## Option 2: build from source
+
+Before configuring CMake, initialize the submodules from the repository root:
+
+```bash
+git submodule update --init --recursive
+```
+
+Then configure and build:
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j
+```
+
+The main executable is written to `build/bin/semba-fdtd`.
+
+## Run a case
+
+The primary workflow uses an input file in the `.fdtd.json` format:
+
+```bash
+build/bin/semba-fdtd -i CASE_NAME.fdtd.json
+```
+
+The detailed input reference lives in [](fdtdjson.md). Example inputs are available in `testData/input_examples/`.
+
+## Recommended next steps
+
+- Read [](running-simulations.md) for the normal execution workflow.
+- Use [](tutorials/index.md) for worked examples.
+- Use [](docker.md) if you prefer containerized build and test workflows.

doc/index.md

@@ -0,0 +1,17 @@
+# semba-fdtd documentation
+
+`semba-fdtd` is an open-source FDTD electromagnetic solver with support for structured meshes, dispersive and anisotropic materials, thin-wire and multiconductor transmission-line models, MPI/OpenMP parallel execution, and multiple post-processing workflows.
+
+This site reorganizes the repository documentation into a browsable guide for users and contributors. The detailed reference material from the existing `doc/` directory remains available here, now connected by section landing pages and Read the Docs-style navigation.
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+
+project-overview
+getting-started
+user-guide
+developer-guide
+solver-topics
+reference
+```

doc/make.bat

@@ -0,0 +1,10 @@
+@ECHO OFF
+
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%SPHINXBUILD%"=="" (
+    set SPHINXBUILD=python -m sphinx
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR%