added more documentation files

Author: mrodrig6

docs/toolchain/s_test_suite_compatibility.md

@@ -0,0 +1,61 @@
+# `s_test_suite_compatibility.m` Documentation
+
+## Overview
+`s_test_suite_compatibility.m` verifies that the finite difference (`m_imr_fd`) and spectral (`m_imr_spectral`) solvers produce compatible results under various model configurations, including thermal effects.
+
+## Major Sections
+
+1. **Initialization**
+   - Clears workspace (`clc`, `clear`, `close`).
+   - Adds necessary paths: `toolchain/`, `src/forward_solver/`, and `tests/`.
+   - Loads test identifiers from `file_ids.mat`.
+
+2. **Preallocation**
+   - Computes `num_tests` as the product of parameter combinations.
+   - Initializes `errors_fd`, `errors_sp`, and `failed_tests` arrays.
+
+3. **Parameter Setup**
+   - Defines parameter vectors:  
+     - `muvec`: viscosity values  
+     - `Gvec`: shear modulus values  
+     - `alphaxvec`: strain-softening exponents  
+     - `lambda1vec`: relaxation times  
+   - Sets error threshold (`threshold = 1e-4`) and counter (`count = 1`).
+
+4. **Nested Test Loop**
+   - Loops over combinations of:  
+     `radial` (1–4), `bubtherm` (0/1), `medtherm` (0/1), `stress` (0–5),  
+     `mu`, `G`, `alphax`, `lambda1` indices.
+   - For each combination:
+     1. Constructs `varin` parameter-value pairs.
+     2. Loads reference results: `Rf` and `Rs` from test MAT files.
+     3. Runs `m_imr_fd` and compares output `Rf_test`; computes L2 error.
+     4. Runs `m_imr_spectral` and compares output `Rs_test`; computes L2 error.
+     5. Records failures where error exceeds `threshold`.
+
+5. **Summary and Exit**
+   - Truncates and cleans `failed_tests`.
+   - If all tests passed, prints success and calls `exit(0)`.
+   - Otherwise, prints failed test indices and raises an error.
+
+## Inputs
+
+| Name             | Description                                    |
+|------------------|------------------------------------------------|
+| `file_ids.mat`   | MAT-file defining `ids` (list of test case IDs)|
+| `m_imr_fd`       | Finite difference solver function              |
+| `m_imr_spectral` | Spectral solver function                       |
+
+## Outputs
+
+- **Console output**:
+  - L2 norm error for each finite-difference and spectral test.
+  - Summary line: pass or fail with indices.
+- **Exit code**:
+  - `0` if all tests pass.
+  - Error thrown (non-zero) if any test fails.
+
+## Notes
+
+- `num_tests` covers all combinations of radial, thermal, stress, and material parameters.
+- Tests use reduced mesh sizes (`Nt=70, Mt=70` for FD; `Nt=12, Mt=12` for spectral) for speed.

docs/toolchain/s_test_suite_equilibrium.md

@@ -0,0 +1,52 @@
+# `s_test_suite_equilibrium.m` Documentation
+
+## Overview
+`s_test_suite_equilibrium.m` checks that both solvers correctly maintain equilibrium conditions (no dynamics) across model variations.
+
+## Major Sections
+
+1. **Initialization**
+   - Clears workspace.
+   - Adds paths: `toolchain/` and `src/forward_solver/`.
+
+2. **Preallocation**
+   - Defines `num_tests` based on parameter loops.
+   - Initializes `errors_fd`, `errors_sp`, `failed_tests`.
+   - Sets `threshold = 1e-14` for high-precision check.
+
+3. **Parameter and Initial Condition Setup**
+   - Sets fixed test parameters:  
+     `masstrans = 0`, `collapse = 0`,  
+     `Req = 100e-6`, `R0 = Req`, `T8 = 298.15`,  
+     `tfin = 1e-5`, `tvector = linspace(0, tfin, 100)`.
+
+4. **Nested Test Loop**
+   - Iterates over `radial` (1–4), `vapor` (0/1),  
+     `bubtherm` (0/1), `medtherm` (0/1), `stress` (0–5).
+   - Constructs `varin` parameter sets.
+   - Runs `m_imr_fd` and `m_imr_spectral` with fine meshes (`Nt=150,Mt=150` FD; `Nt=12,Mt=12` spectral).
+   - Computes equilibrium error: `abs(norm(R_test,2)/10 - 1)`.
+   - Records failures if error exceeds `threshold`.
+
+5. **Summary and Exit**
+   - Cleans up `failed_tests`.
+   - Prints pass or fail message.
+   - Exits with `0` on success or `1` on failure.
+
+## Inputs
+
+| Name             | Description                                    |
+|------------------|------------------------------------------------|
+| `m_imr_fd`       | Finite difference solver function              |
+| `m_imr_spectral` | Spectral solver function                       |
+| Script parameters| Equilibrium test parameters (e.g., `Req`, `R0`)|
+
+## Outputs
+
+- **Console output**: Equilibrium error norms and summary.
+- **Exit code**: `0` if all within `threshold`, `1` otherwise.
+
+## Notes
+
+- Equilibrium condition implies the bubble radius remains constant.
+- High-precision tolerance ensures numerical consistency.

docs/toolchain/s_test_suite_masstrans.md

@@ -0,0 +1,50 @@
+# `s_test_suite_masstrans.m` Documentation
+
+## Overview
+`s_test_suite_masstrans.m` validates the finite difference solver’s mass transfer implementation under various model settings.
+
+## Major Sections
+
+1. **Initialization**
+   - Clears workspace.
+   - Adds paths: `src/forward_solver/` and `tests/`.
+   - Loads `file_ids.mat`.
+
+2. **Preallocation**
+   - Computes `num_tests`.
+   - Initializes `errors_fd` and `failed_tests`.
+   - Sets `threshold = 1e-5`, `count = 1`.
+
+3. **Test Parameter Setup**
+   - Defines `tvector` for simulation.
+   - Fixes `masstrans = 1`, `vapor = 1`, `collapse = 1`.
+   - Sets bubble geometry: `R0`, `Req`.
+   - Defines model vectors: `radial`, `bubtherm`, `medtherm`, `stress`.
+
+4. **Loop Over Test Cases**
+   - Iterates over all combinations.
+   - Builds `varin` parameters.
+   - Loads reference `Rm` from test files.
+   - Executes `m_imr_fd(...,'Nt',30,'Mt',70)`, computes L2 error.
+   - Records failures above `threshold`.
+
+5. **Summary**
+   - Trims `failed_tests`.
+   - Prints pass/fail summary (no automatic exit).
+
+## Inputs
+
+| Name            | Description                          |
+|-----------------|--------------------------------------|
+| `file_ids.mat`  | Test case identifiers                |
+| `m_imr_fd`      | Finite difference solver function    |
+
+## Outputs
+
+- **Console output**: L2 norm errors per test and summary.
+- **Error flags**: `failed_tests` indices where mass transfer failed.
+
+## Notes
+
+- Script does not exit on failure to allow further analysis.
+- Uses moderate resolution (`Nt=30`, `Mt=70`) for faster execution.