Improve doc

.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # setuptools_scm needs the tags
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package and docs dependencies
+        run: pip install .[docs]
+      # Notebooks are converted with their saved outputs, not executed
+      - name: Convert example notebooks
+        run: jupyter nbconvert --to markdown docs/examples/*/*.ipynb
+      - name: Build site
+        run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

.gitignore

@@ -2,4 +2,11 @@
 __pycache__/
 .vscode/
 interpcore.egg-info
-_version.py
+_version.py
+
+# documentation build
+site/
+.cache/
+# generated from the notebooks by nbconvert at build time
+docs/examples/*/*.md
+docs/examples/*/*_files/

README.md

@@ -1,29 +1,30 @@
 # InterpCore
 
-A Python library for interpolating physical field data (electromagnetic forces, heat flux, etc.) between different mesh representations and exporting to ANSYS APDL format.
+[![Documentation](https://img.shields.io/badge/docs-online-blue)](https://fusion4energy.github.io/InterpCore/)
+
+A Python library for interpolating physical field data (electromagnetic forces, heat
+flux, heat generation, convection boundary conditions) between different mesh
+representations and exporting the result to ANSYS APDL format.
+
+**Full documentation: <https://fusion4energy.github.io/InterpCore/>**
 
 ## Features
 
-- **Multiple interpolation kernels**: Distance-weighted, FEM-based, K-nearest neighbors, closest point
-- **Flexible query methods**: K-nearest neighbors or radius-based search
-- **Support for multiple load types**: 
-  - EM forces (3-component vector fields)
-  - Heat flux (scalar fields)
-  - Heat generation (volumetric)
-  - Heat Transfer Coefficient + bulk fluid temperature (convection BCs)
-- **Analysis tools**:
-  - Scalar field integration for computing total heat generation, flux, etc.
-  - EM force resultant computation for validating force/moment conservation
-- **Export to ANSYS APDL**: Direct export of interpolated results in APDL format
-- **Visualization**: Built-in VTK export for ParaView or PyVista visualization
-- **Efficient**: KDTree-based spatial queries for fast neighbor searches
+- Multiple interpolation kernels: distance-weighted, FEM-based, average, weighted
+  average, closest point
+- K-nearest or radius-based neighbour search (KDTree)
+- EM forces, heat flux, heat generation and HTC + bulk temperature
+- Force/moment resultants and scalar integrals to validate the interpolation
+- Direct export to ANSYS APDL and VTK output for ParaView/PyVista
 
 ## Installation
 
 ```bash
 pip install interpcore
 ```
 
+Requires Python ≥ 3.11.
+
 ## Quick Start
 
 ```python
@@ -33,204 +34,33 @@ from interpcore.config import (
     ColumnsConfig,
     QUERY_TYPE,
     INTERPOLATED_LOAD_TYPE,
+    INTERPOLATION_KERNEL,
 )
-from interpcore.kernels import INTERPOLATION_KERNEL
 
-# Configure interpolation
 config = InterpolationConfig(
-    method=QUERY_TYPE.K,  # type of neighbour search
-    param=5,  # parameter relative to the neighbour search (K or radius)
-    max_distance=2.0,  # filter by a max radius of search (in case of K is used)
-    coincidence_tolerance=0.01,  # tolerance to consider two nodes coincident
-    kernel=INTERPOLATION_KERNEL.DISTANCE_WEIGHTED,  # How to interpolate
-    multithread=False,  # use or not multithread
-    interpolated_load=INTERPOLATED_LOAD_TYPE.EM_FORCE,  # type of load that is being interpolated
+    method=QUERY_TYPE.K,
+    param=5,
+    max_distance=2.0,
+    coincidence_tolerance=0.01,
+    kernel=INTERPOLATION_KERNEL.DISTANCE_WEIGHTED,
+    multithread=False,
+    interpolated_load=INTERPOLATED_LOAD_TYPE.EM_FORCE,
 )
-
-# Define column indices for the input files
 columns = ColumnsConfig(id=0, dest_xyz=1, source_xyz=1, value=4)
 
-# Create interpolator and run
 interpolator = Interpolator(
     path_to_src_folder="source_data",
     path_to_dest_mesh="destination_mesh.txt",
     config=config,
     columns=columns,
 )
-
-# Interpolate all source files
 interpolator.interpolate_all()
-
-# Export to ANSYS format
 interpolator.export_to_ansys("output_directory")
-
-# Optional: Build VTK for visualization. If outdir=None they are not exported
-interpolator.build_vtk_output(outdir="vtk_output")
 ```
 
-## Interpolation Configuration
-
-Two dataclass objects fully control how the interpolation is performed.
-
-### `InterpolationConfig`
-
-Controls the spatial search strategy, the interpolation kernel, and the target load type.
-
-| Parameter | Type | Description |
-|---|---|---|
-| `method` | `QUERY_TYPE` | Neighbour search strategy: `QUERY_TYPE.K` (K-nearest) or `QUERY_TYPE.RADIUS` (radius-based). |
-| `param` | `int \| float` | Parameter for the chosen method: number of neighbours for `K`, radius (same unit as coordinates) for `RADIUS`. |
-| `max_distance` | `float` | Maximum distance (same unit as coordinates) beyond which a destination node is not considered a neighbour, even when using `QUERY_TYPE.K`. Acts as a hard cutoff. |
-| `coincidence_tolerance` | `float` | Distance below which two nodes are treated as coincident and the source value is copied directly without interpolation. |
-| `kernel` | `INTERPOLATION_KERNEL` | Algorithm used to assign a value from the neighbourhood. See [Interpolation Kernels](#interpolation-kernels). |
-| `multithread` | `bool` | Whether to parallelise the interpolation loop using threads. |
-| `interpolated_load` | `INTERPOLATED_LOAD_TYPE` | Physical quantity being interpolated. Determines the number of components and the APDL export format. |
-| `accept_no_neighbor` | `bool` | If `False` (default), raise an error when a destination node has no neighbour within `max_distance`. If `True`, assign zero to those nodes silently. |
-
-> **Note**: not every kernel is compatible with every load type. See [Kernel–Load Compatibility](#kernel-load-compatibility).
-
-### `ColumnsConfig`
-
-Describes the zero-based column indices in both the source data files and the destination mesh file. All three coordinate components (x, y, z) are expected in consecutive columns starting at the given index.
-
-| Parameter | Type | Description |
-|---|---|---|
-| `source_xyz` | `int` | Index of the **x** column in the source file; y and z must follow immediately. |
-| `value` | `int` | Index of the column containing the scalar (or first component) value to interpolate from the source file. |
-| `dest_xyz` | `int` | Index of the **x** column in the destination mesh file; y and z must follow immediately. |
-| `id` | `int` | Index of the node-ID column in the destination mesh file. |
-| `volume_area` | `int \| None` | Index of the volume/area column in the destination mesh file. Required for scalar integrals and for EM force density inputs. |
-
-## Interpolation checks and outputs
-
-## Analysis Methods
-
-After interpolation, InterpCore provides methods to analyze and validate results:
-
-### Scalar Integrals
-
-For scalar fields (heat flux, heat generation), you can compute the total integral over the destination mesh:
-
-```python
-# Requires volume or area data in the destination mesh
-columns = ColumnsConfig(
-    id=0, dest_xyz=1, source_xyz=1, value=4, volume_area=4
-)  # volume_area points to the vol/area column
-
-interpolator = Interpolator(
-    path_to_src_folder="source_data",
-    path_to_dest_mesh="destination_mesh.txt",
-    config=config,
-    columns=columns,
-)
-
-interpolator.interpolate_all()
-
-# Compute integrals (e.g., total heat generation in W)
-integrals = interpolator.compute_scalar_integrals()
-# Returns: {"data_001": array([total_value])}
-```
-
-**Note**: The destination mesh must include volume (for 3D elements) or area (for 2D elements) data. Use the APDL scripts in [`apdl-scripts/`](apdl-scripts/) to export element centroids with volumes and areas.
-
-### EM Force Resultants
-
-For EM force fields, you can compute force and moment resultants to verify conservation:
-
-```python
-# After interpolation with EM_FORCE load type
-resultants = interpolator.compute_EM_resultants(pole=np.array([0.0, 0.0, 0.0]))
-
-# Returns for each source file:
-# {
-#     "force_001": {
-#         "R_F_EM": [Fx, Fy, Fz],           # Total force from source data
-#         "R_F_Mech": [Fx, Fy, Fz],         # Total force from interpolated data
-#         "R_M_EM": [Mx, My, Mz],           # Total moment from source data
-#         "R_M_Mech": [Mx, My, Mz],         # Total moment from interpolated data
-#         "f_err_comp": [ex, ey, ez],       # Relative force error by component
-#         "m_err_comp": [ex, ey, ez],       # Relative moment error by component
-#         "Unmapped_EM_Force": float        # Norm of unmapped forces
-#     }
-# }
-```
-
-This is useful for validating that the interpolation preserves global force and moment equilibrium. Small errors indicate good interpolation quality.
-
-## Examples
-
-Complete working examples with sample data are available in the [`doc/`](doc/) folder:
-
-- **[Heat Flux Example](doc/heat_flux/heat_flux.ipynb)**: Scalar field interpolation using the AVERAGE kernel
-- **[Heat Generation Example](doc/heat_gen/heat_gen.ipynb)**: Volumetric heat generation using the CLOSEST kernel
-- **[EM Force Example](doc/em_force/em_force.ipynb)**: Vector field interpolation with glyph visualization
-- **[HTC Example](doc/htc/htc.ipynb)**: Convection boundary condition interpolation (HTC + bulk fluid temperature) 
-
-Each example includes:
-- Sample mesh files
-- Sample data files
-- Jupyter notebook with full workflow
-- Visualization with PyVista
-
-## Configuration Options
-
-### Query Methods
-- `QUERY_TYPE.K`: K-nearest neighbors (param = number of neighbors)
-- `QUERY_TYPE.RADIUS`: Radius-based search (param = radius in same unit as coordinates)
-
-### Interpolation Kernels
-
-#### Source-to-target
-
-Each source point is distributed to destination neighbours:
-
-- `DISTANCE_WEIGHTED`: Weight by inverse distance
-- `FEM`: FEM-based interpolation
-
-
-#### Target-to-source 
-A value is assigned to each destination point based on source neighbours
-
-- `CLOSEST`: Use closest source point value
-- `AVERAGE`: Simple average of neighbors
-- `AVERAGE_WEIGHTED`: Average the neighbours values but weighting them by distance (the closer the more important).
-
-### Load Types
-- `EM_FORCE`: 3-component vector fields (Fx, Fy, Fz). If "vol" column is provided the forces are
-    interpreted as force densities and will be multiplied by the volume.
-- `HEAT_FLUX`: Scalar fields for surface heat flux
-- `HEAT_GEN`: Scalar fields for volumetric heat generation
-- `HTC`: 2-component convection boundary condition — Heat Transfer Coefficient and bulk fluid (reference) temperature. Exported as `SFE,,CONV,1` and `SFE,,CONV,2` in APDL.
-
-### Kernel-Load Compatibility
-
-Not every kernel can be used with every load type. The kernels are divided into two families based on the direction of the mapping:
-
-| Kernel | Family | Compatible loads |
-|---|---|---|
-| `DISTANCE_WEIGHTED` | Source-to-target | `EM_FORCE` only |
-| `FEM` | Source-to-target | `EM_FORCE` only |
-| `AVERAGE` | Target-to-source | `HEAT_FLUX`, `HEAT_GEN`, `HTC` |
-| `AVERAGE_WEIGHTED` | Target-to-source | `HEAT_FLUX`, `HEAT_GEN`, `HTC` |
-| `CLOSEST` | Target-to-source | `HEAT_FLUX`, `HEAT_GEN`, `HTC` |
-
-Source-to-target kernels distribute each source point's contribution onto its destination neighbours, which is suited to force conservation in EM applications. Target-to-source kernels assign a value to each destination node by aggregating its source neighbours, which is better suited to scalar field interpolation. Using an incompatible combination raises a `ConfigurationError` at construction time.
-
-## File Format
-
-The file format is pretty free, header, no header, commas, tabs....
-The important part is that the correct index columns are specified when creating the interpolator.
-
-Destination mesh input files can be created using the apdl scripts included in this repository
-[here](/apdl-scripts/).
-
-## Requirements
-
-- Python ≥ 3.10
-- scikit-learn
-- pandas
-- tqdm
-- pyvista
+See the [documentation](https://fusion4energy.github.io/InterpCore/) for the
+configuration options, the kernels and load types, and the
+[examples](docs/examples/) for complete Jupyter notebook workflows.
 
 ## License
 

docs/api/config.md

@@ -0,0 +1,3 @@
+# Configuration
+
+::: interpcore.config

docs/api/dest_tree.md

@@ -0,0 +1,3 @@
+# Destination tree
+
+::: interpcore.dest_tree

docs/api/errors.md

@@ -0,0 +1,3 @@
+# Errors
+
+::: interpcore.errors

docs/api/interpolator.md

@@ -0,0 +1,3 @@
+# Interpolator
+
+::: interpcore.interpolator

docs/api/kernels.md

@@ -0,0 +1,8 @@
+# Kernels
+
+The kernel maths is described in the [user guide](../user-guide/kernels.md).
+
+::: interpcore.kernels
+    options:
+      members:
+        - interpolate_block

docs/api/parsers.md

@@ -0,0 +1,3 @@
+# Parsers
+
+::: interpcore.parsers