diff --git a/.gitignore b/.gitignore index dbead188f..c869a874e 100755 --- a/.gitignore +++ b/.gitignore @@ -40,6 +40,7 @@ venv/ build/ build-*/ build_test/ +doc/_build/ CMakeUserPresets.json CMakeSettings.json diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..b96351b68 --- /dev/null +++ b/.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 diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..6b0eb3404 --- /dev/null +++ b/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)" diff --git a/doc/architecture.md b/doc/architecture.md new file mode 100644 index 000000000..38aaa7b7e --- /dev/null +++ b/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. diff --git a/doc/cli-reference.md b/doc/cli-reference.md new file mode 100644 index 000000000..2f1c04791 --- /dev/null +++ b/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. diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..1f4f10594 --- /dev/null +++ b/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/", +} diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 000000000..c912eb66d --- /dev/null +++ b/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. diff --git a/doc/developer-guide.md b/doc/developer-guide.md new file mode 100644 index 000000000..90059bf33 --- /dev/null +++ b/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 +``` diff --git a/doc/development.md b/doc/development.md index a4dd8aa4b..fba45b601 100644 --- a/doc/development.md +++ b/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)) \ No newline at end of file +([source](https://github.com/Microsoft/MIEngine/wiki/Troubleshoot-attaching-to-processes-using-GDB)) diff --git a/doc/fdtdjson.md b/doc/fdtdjson.md index c7f08b9ee..336262ea3 100644 --- a/doc/fdtdjson.md +++ b/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 `` 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 ``, 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 `` 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 `` with at least two coordinates. - + `cell`, containing a list of one or more `` defined following the [interval convention](#the-interval-convention). + + `cell`, containing a list of one or more `` defined following the [interval convention](#interval-convention). + + If `cell` represents a conformal element it will contain a list of zero or more and a list of , 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, `` and `` 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: + `` and `` 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 `` 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 `` 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: -+ `` 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). ++ `` 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). + `` must be a label of the ones defined below. Some examples of source `type` are `planewave` or `nodalSource`. + `` 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. diff --git a/doc/getting-started.md b/doc/getting-started.md new file mode 100644 index 000000000..d2d4fcf2f --- /dev/null +++ b/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: + +- + +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. diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 000000000..a40d360ca --- /dev/null +++ b/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 +``` diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 000000000..d9223d86c --- /dev/null +++ b/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% diff --git a/doc/outputs.md b/doc/outputs.md new file mode 100644 index 000000000..6a05c80b0 --- /dev/null +++ b/doc/outputs.md @@ -0,0 +1,21 @@ +# Outputs and postprocessing + +`semba-fdtd` supports several output styles, depending on the enabled features and the probes present in the input file. + +## Common output forms + +- Plain-text probe data, typically written as `.dat` files. +- XDMF + HDF5 outputs for snapshots and movies. +- VTK outputs for visualization workflows such as ParaView. + +## How outputs are configured + +Outputs are driven by the `probes` section of the `.fdtd.json` input. Probe type, sampling period, field/component selection, and spatial domain determine what gets written. + +The full probe and domain reference is part of [](fdtdjson.md). + +## Postprocessing workflows + +- Use ParaView or other VTK/XDMF-aware tools for field visualization. +- Use Python scripts from `testData/` and `doc/tutorials/` as examples for reading and plotting probe outputs. +- Use the Python wrapper tests and examples when you want to drive solver execution and analysis programmatically. diff --git a/doc/project-overview.md b/doc/project-overview.md new file mode 100644 index 000000000..65af85130 --- /dev/null +++ b/doc/project-overview.md @@ -0,0 +1,30 @@ +# Project overview + +`semba-fdtd` solves electromagnetic problems with a finite-difference time-domain core and optional multiconductor transmission-line coupling. The codebase is centered on a Fortran solver, with CMake-based builds, GoogleTest-based unit tests, and Python tooling for integration tests and preprocessing/postprocessing workflows. + +## Main capabilities + +- MPI-based distributed execution and OpenMP parallelism. +- Structured regular or rectilinear meshes. +- PEC, PMC, Mur, and CPML boundary conditions. +- Lossless, lossy, dispersive, anisotropic, and thin-material models. +- Embedded wires and multiconductor transmission-line networks with optional ngspice coupling. +- Probe-based outputs, near-to-far field transforms, VTK export, and XDMF/HDF5 output. + +## Documentation map + +- Start with [](getting-started.md) for installation, build, and first-run steps. +- Use [](user-guide.md) for input files, tutorials, outputs, and container workflows. +- Use [](developer-guide.md) for architecture, testing, and contribution workflows. +- Use [](solver-topics.md) for focused solver-domain documentation such as MTLN. + +## Repository layout at a glance + +- `src_main_pub/`: main solver, launcher, preprocessing, postprocessing, core types. +- `src_json_parser/`: FDTD JSON parser. +- `src_mtln/`: multiconductor transmission-line solver and ngspice interface. +- `src_conformal/`: conformal mapping support. +- `src_wires_pub/`: wire models. +- `test/`: unit and Python integration tests. +- `testData/`: sample cases, inputs, and supporting assets. +- `doc/`: documentation sources, now also used to build this site. diff --git a/doc/reference.md b/doc/reference.md new file mode 100644 index 000000000..fd5e8d5c4 --- /dev/null +++ b/doc/reference.md @@ -0,0 +1,10 @@ +# Reference + +Use this section for command-line basics and the input format reference. + +```{toctree} +:maxdepth: 2 + +cli-reference +fdtdjson +``` diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 000000000..a13cd9b0e --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,3 @@ +sphinx>=8,<9 +myst-parser>=4,<5 +sphinx-rtd-theme>=3,<4 diff --git a/doc/running-simulations.md b/doc/running-simulations.md new file mode 100644 index 000000000..58f612f20 --- /dev/null +++ b/doc/running-simulations.md @@ -0,0 +1,25 @@ +# Running simulations + +## Input format + +The solver consumes `.fdtd.json` files. The complete object-by-object reference is documented in [](fdtdjson.md), and sample inputs live in `testData/input_examples/`. + +## Basic command + +Run the solver from the directory that contains your case files: + +```bash +build/bin/semba-fdtd -i CASE_NAME.fdtd.json +``` + +If you installed a release binary instead of building from source, replace `build/bin/semba-fdtd` with the path to the installed executable. + +## Typical workflow + +1. Prepare the `.fdtd.json` input and any referenced excitation files. +2. Run the solver. +3. Inspect the generated probe data, VTK/XDMF/HDF5 outputs, or postprocess them with the Python tooling used by the repository tests and examples. + +## Examples and preprocessing + +The repository contains end-to-end examples in `testData/` and more guided narrative material in [](tutorials/index.md). The Python wrapper examples also illustrate how to generate excitation files and automate postprocessing around the solver. diff --git a/doc/solver-topics.md b/doc/solver-topics.md new file mode 100644 index 000000000..1ebe903d2 --- /dev/null +++ b/doc/solver-topics.md @@ -0,0 +1,9 @@ +# Solver topics + +These pages cover solver-domain topics that go beyond the basic getting-started workflow. + +```{toctree} +:maxdepth: 2 + +mtln +``` diff --git a/doc/testing.md b/doc/testing.md new file mode 100644 index 000000000..c9c171bf2 --- /dev/null +++ b/doc/testing.md @@ -0,0 +1,50 @@ +# Testing + +The repository uses both compiled tests and Python integration tests. + +## Unit tests + +After building with tests enabled, run: + +```bash +./build/bin/fdtd_tests +``` + +## Python integration tests + +Create a virtual environment and install the existing test dependencies: + +```bash +python3 -m venv .venv +source .venv/bin/activate +python3 -m pip install -r requirements.txt +``` + +Then run the test suite from the repository root: + +```bash +pytest test/ --durations=20 +``` + +Running from the repository root matters because several tests reference `testData/` with relative paths. + +## Test markers + +The Python suite defines these markers in `pytest.ini`: + +- `mtln` +- `codemodel` +- `hdf` +- `mpi` + +Examples: + +```bash +pytest test/ -m mtln +pytest test/ -m hdf +pytest test/ -m mpi +``` + +## Containerized test runs + +If you prefer Docker-based workflows, [](docker.md) documents how to run both the unit tests and the Python suite inside the provided container setup. diff --git a/doc/tutorials/index.md b/doc/tutorials/index.md new file mode 100644 index 000000000..6efb3e692 --- /dev/null +++ b/doc/tutorials/index.md @@ -0,0 +1,9 @@ +# Tutorials + +Worked examples live here. They complement the raw reference docs by showing complete simulation workflows. + +```{toctree} +:maxdepth: 2 + +veritasium/veritasium +``` diff --git a/doc/tutorials/veritasium/veritasium.md b/doc/tutorials/veritasium/veritasium.md index 6beb0583f..051f1a980 100644 --- a/doc/tutorials/veritasium/veritasium.md +++ b/doc/tutorials/veritasium/veritasium.md @@ -1,10 +1,10 @@ # Example `smbjson` from The Big Misconception About Electricity -This JSON models the problem presented in [The Big Misconception About Electricity](https://www.youtube.com/watch?v=bHIhgxav9LY) by Veritasium. The general structure of the JSON can be found in the [FDTD-JSON format](https://github.com/OpenSEMBA/fdtd/blob/main/doc/smbjson.md). +This JSON models the problem presented in [The Big Misconception About Electricity](https://www.youtube.com/watch?v=bHIhgxav9LY) by Veritasium. The general structure of the JSON can be found in the [FDTD-JSON format](../../fdtdjson.md). ## JSON layout in the example case -Each object in the JSON is shown for the example case. As indicated in [smbjson.md](https://github.com/OpenSEMBA/fdtd/blob/main/doc/smbjson.md), all units are assumed to be SI-MKS. +Each object in the JSON is shown for the example case. As indicated in [](../../fdtdjson.md), all units are assumed to be SI-MKS. ### `general` @@ -313,4 +313,3 @@ plt.show() ``` ![Current vs time](./veritasium.png) - diff --git a/doc/user-guide.md b/doc/user-guide.md new file mode 100644 index 000000000..c25a608c9 --- /dev/null +++ b/doc/user-guide.md @@ -0,0 +1,14 @@ +# User guide + +The user-facing documentation is split between the input format reference, execution workflow notes, output descriptions, and worked examples. + +```{toctree} +:maxdepth: 2 + +running-simulations +outputs +docker +tutorials/index +``` + +Use [](fdtdjson.md) for the complete input-file reference.