Multi-Scenario VFP Generation Framework (#1861)

* add functionality

* update docs

* update

Author: EvenSol

.github/copilot-instructions.md

@@ -227,7 +227,11 @@ Before committing, run `./mvnw javadoc:javadoc` to catch JavaDoc errors early.
 - **Auto-Validation for New Equipment**: When creating a new class that extends `ProcessEquipmentBaseClass`, ALWAYS generate a `validateSetup()` method that checks: (1) required input streams are connected, (2) required parameters are set and within valid ranges, (3) return `ValidationResult` with remediation hints for each issue.
 - **Auto-Annotation for Public Methods**: When adding new public methods to core classes (SystemInterface, ProcessEquipmentInterface), consider adding `@AIExposable` annotation with description, category, example, and `@AIParameter` annotations documenting valid ranges/options.
 - **Jupyter Notebook Examples**: When creating Jupyter notebook examples, ensure they run end-to-end and reflect the latest API changes; place them in the `notebooks/` directory and link to them from the main documentation. Follow the neqsim-python direct Java API bindings as shown at https://github.com/equinor/neqsim-python?tab=readme-ov-file#4-direct-java-access-full-control
-- **Add markdown files with documentation**: When adding documentation as markdown files be sure to update REFERENCE_MANUAL_INDEX.md applyTo: **/*.md
+- **Add markdown files with documentation**: When adding documentation as markdown files:
+  1. Update `REFERENCE_MANUAL_INDEX.md` with the new file entry
+  2. Update the relevant section's `index.md` (e.g., `docs/examples/index.md`)
+  3. Verify ALL links to other docs using `file_search` before adding them
+  4. See "Documentation Links (MANDATORY)" section below for link guidelines
 
 ## Markdown Documentation Guidelines (MANDATORY)
 
@@ -363,6 +367,87 @@ After adding equations, preview locally or check that:
 2. Inline math renders within the text flow
 3. No raw LaTeX syntax (backslashes, braces) appears in rendered output
 
+### Documentation Links (MANDATORY)
+
+When adding links to other documentation files, follow these rules to prevent broken links:
+
+#### Link Verification Rules
+
+1. **ALWAYS verify target files exist** before adding links:
+   - Use `file_search` to confirm the file exists in the repository
+   - Check the exact path and filename (case-sensitive on some systems)
+
+2. **Use correct relative paths** based on the source file location:
+   - From `docs/fielddevelopment/` to `docs/process/`: use `../process/filename.md`
+   - From `docs/examples/` to `docs/tutorials/`: use `../tutorials/filename.md`
+   - Within same folder: use just `filename.md`
+
+3. **Prefer existing documentation** over creating placeholder links:
+   - If a linked file doesn't exist, either create it OR link to an existing alternative
+   - NEVER add links to files that don't exist
+
+#### Common Documentation Paths
+
+| Documentation Area | Path | Example Files |
+|--------------------|------|---------------|
+| Process equipment | `docs/process/` | `separators.md`, `compressors.md`, `heat-exchangers.md` |
+| Field development | `docs/fielddevelopment/` | `pressure_boundary_optimization.md`, `CAPACITY_CONSTRAINT_FRAMEWORK.md` |
+| Thermodynamics | `docs/thermo/` | `equations-of-state.md`, `flash-calculations.md` |
+| Examples | `docs/examples/` | `*.ipynb`, `*.java`, `index.md` |
+| Tutorials | `docs/tutorials/` | Getting started guides |
+| Troubleshooting | `docs/troubleshooting/` | Common issues and solutions |
+
+#### When Adding New Documentation
+
+1. **Update index files** when creating new documentation:
+   - Add entry to `docs/REFERENCE_MANUAL_INDEX.md` (master index of 360+ files)
+   - Add entry to the relevant section's `index.md` (e.g., `docs/examples/index.md`)
+
+2. **Cross-reference related docs** with verified links:
+   ```markdown
+   ## Related Documentation
+   
+   - [Pressure Boundary Optimization](pressure_boundary_optimization.md)
+   - [Capacity Constraint Framework](CAPACITY_CONSTRAINT_FRAMEWORK.md)
+   ```
+
+3. **For Jupyter notebooks**, also add to:
+   - `docs/examples/index.md` - Examples index
+   - `docs/REFERENCE_MANUAL_INDEX.md` - Master reference
+
+#### Link Format Examples
+
+```markdown
+<!-- Same directory -->
+[Related Topic](related-topic.md)
+
+<!-- Parent directory -->
+[Process Overview](../process/index.md)
+
+<!-- Sibling directory -->
+[Tutorial](../tutorials/getting-started.md)
+
+<!-- Link to specific section -->
+[VFP Tables](pressure_boundary_optimization.md#vfp-generation)
+
+<!-- Link to Java example -->
+[Java Example](MultiScenarioVFPExample.java)
+
+<!-- Link to notebook -->
+[Notebook Tutorial](ProductionSystem_BottleneckAnalysis.ipynb)
+```
+
+#### Broken Link Prevention Checklist
+
+Before finalizing documentation with links:
+
+- [ ] All linked `.md` files exist (use `file_search("**/filename.md")`)
+- [ ] All linked `.ipynb` notebooks exist
+- [ ] All linked `.java` examples exist
+- [ ] Relative paths are correct for source file location
+- [ ] Index files updated for new documentation
+- [ ] No links to planned-but-not-created files
+
 ## Mechanical Design Implementation Pattern (MANDATORY)
 
 When implementing mechanical design for any process equipment, follow this established architecture pattern:

docs/REFERENCE_MANUAL_INDEX.md

@@ -188,6 +188,7 @@ Fluid characterization handles plus fraction splitting, property estimation, and
 | **Reading Fluid Properties** | [docs/thermo/reading_fluid_properties.md](thermo/reading_fluid_properties) | **Comprehensive guide to calculating and reading properties from fluids, phases, and components** |
 | Properties Overview | [docs/thermo/physical_properties.md](thermo/physical_properties) | Physical property calculations |
 | Physical Props Module | [docs/physical_properties/README.md](physical_properties/) | Physical properties module |
+| **H2S Distribution** | [docs/thermo/H2S_distribution_guide.md](thermo/H2S_distribution_guide) | **H2S phase distribution modeling with SRK, PR, CPA, Electrolyte-CPA** |
 | Viscosity Models | [docs/wiki/viscosity_models.md](wiki/viscosity_models) | Viscosity calculation models |
 | Viscosity Detailed | [docs/physical_properties/viscosity_models.md](physical_properties/viscosity_models) | Detailed viscosity models |
 | Density Models | [docs/physical_properties/density_models.md](physical_properties/density_models) | Density calculation models |
@@ -197,7 +198,7 @@ Fluid characterization handles plus fraction splitting, property estimation, and
 | Scale Potential | [docs/physical_properties/scale_potential.md](physical_properties/scale_potential) | Scale potential calculations |
 | Steam Tables | [docs/wiki/steam_tables_if97.md](wiki/steam_tables_if97) | IF97 steam table implementation |
 | Thermodynamic Workflows | [docs/thermo/thermodynamic_workflows.md](thermo/thermodynamic_workflows) | Common thermodynamic workflows |
-| Interaction Tables | [docs/thermo/inter_table_guide.md](thermo/inter_table_guide) | Binary interaction parameters |
+| Interaction Tables | [docs/thermo/inter_table_guide.md](thermo/inter_table_guide) | Binary interaction parameters | |
 
 ### Chapter 10: Hydrates & Flow Assurance
 
@@ -255,6 +256,7 @@ Fluid characterization handles plus fraction splitting, property estimation, and
 | Distillation | [docs/process/equipment/distillation.md](process/equipment/distillation) | Distillation columns |
 | Distillation Wiki | [docs/wiki/distillation_column.md](wiki/distillation_column) | Distillation column details |
 | Absorbers | [docs/process/equipment/absorbers.md](process/equipment/absorbers) | Absorption equipment |
+| **H2S Scavenger** | [docs/process/H2S_scavenger_guide.md](process/H2S_scavenger_guide) | **Chemical scavenging of H2S from gas - triazine, glyoxal, iron sponge, caustic, liquid redox** |
 | Membrane | [docs/wiki/membrane_separation.md](wiki/membrane_separation) | Membrane separation |
 | Membrane Equipment | [docs/process/equipment/membranes.md](process/equipment/membranes) | Membrane equipment |
 | Filters | [docs/process/equipment/filters.md](process/equipment/filters) | Filter equipment |
@@ -753,6 +755,7 @@ Extended risk analysis capabilities implementing P1-P7 priority improvements for
 | **Integrated Framework** | [docs/fielddevelopment/INTEGRATED_FIELD_DEVELOPMENT_FRAMEWORK.md](fielddevelopment/INTEGRATED_FIELD_DEVELOPMENT_FRAMEWORK) | PVT→Reservoir→Well→Process integration guide |
 | **Strategy** | [docs/fielddevelopment/FIELD_DEVELOPMENT_STRATEGY.md](fielddevelopment/FIELD_DEVELOPMENT_STRATEGY) | Field development strategy and roadmap |
 | **Late-Life Operations** | [docs/fielddevelopment/LATE_LIFE_OPERATIONS.md](fielddevelopment/LATE_LIFE_OPERATIONS) | **Turndown, debottlenecking, and decommissioning timing analysis** |
+| **Multi-Scenario VFP Generation** | [docs/fielddevelopment/MULTI_SCENARIO_PRODUCTION_OPTIMIZATION.md](fielddevelopment/MULTI_SCENARIO_PRODUCTION_OPTIMIZATION) | VFP tables with varying GOR/water cut for reservoir simulation coupling |
 | Field Planning | [docs/wiki/field_development_planning.md](wiki/field_development_planning) | Field development planning |
 | Field Engine | [docs/simulation/field_development_engine.md](simulation/field_development_engine) | Field development engine |
 | **Economics** | [docs/process/economics/README.md](process/economics/) | Economics module: NPV, IRR, tax models, decline curves |
@@ -819,6 +822,8 @@ Extended risk analysis capabilities implementing P1-P7 priority improvements for
 | **ESP Pump Tutorial** | [docs/examples/ESP_Pump_Tutorial.md](examples/ESP_Pump_Tutorial) | **Electric Submersible Pump simulation and sizing** |
 | **Graph-Based Simulation** | [docs/examples/GraphBasedProcessSimulation.md](examples/GraphBasedProcessSimulation) | **Graph-based process simulation tutorial** |
 | **Field Development Workflow** | [docs/examples/FieldDevelopmentWorkflow.md](examples/FieldDevelopmentWorkflow) | **End-to-end field development workflow example** |
+| **Multi-Scenario VFP Tutorial** | [docs/examples/MultiScenarioVFP_Tutorial.ipynb](examples/MultiScenarioVFP_Tutorial) | **VFP generation with varying GOR/water cut scenarios** |
+| **Production System Bottleneck Analysis** | [docs/examples/ProductionSystem_BottleneckAnalysis.ipynb](examples/ProductionSystem_BottleneckAnalysis) | **Multi-well system optimization, bottleneck identification, and well prioritization** |
 | **MPC Integration Tutorial** | [docs/examples/MPC_Integration_Tutorial.md](examples/MPC_Integration_Tutorial) | **Model Predictive Control integration example** |
 | **AI Platform Integration** | [docs/examples/AIPlatformIntegration.md](examples/AIPlatformIntegration) | **AI platform integration tutorial** |
 | Examples Index | [docs/examples/index.md](examples/index) | Examples documentation index |