3D_EDFM_SIM-X/docs/project_status_overview.md

# EDFM GUI Project Status Overview

## Project Goal

Build a MATLAB GUI for the existing EDFM simulator so that users can:

- edit simulation parameters through a graphical interface
- load and save input configurations
- run the solver from the GUI
- view run status and basic results
- import and export results
- eventually call existing plotting functions from the result page

The current solver code already exists.
The main work is:

1. extracting and organizing parameters from the existing case scripts and helper files
2. building a GUI around a unified configuration format and runtime entry point

## Functional Scope Agreed So Far

### GUI Structure

The GUI should be organized by the `Part1` to `Part8` logic already present in the case `main1.m` files.

Recommended page split:

- `Part1 模型`
- `Part2 网格`
- `Part3 裂缝`
- `Part4 离散化/岩性`
- `Part5 流动模型`
- `Part6 井与制度`
- `Part7 求解器`
- `结果`

There is also a top toolbar for:

- template loading
- config import/export
- run
- result import/export

### Data Management

The main editable runtime format is now defined as MATLAB `struct`.

Current persistence direction:

- config import/export: `.mat`
- result import/export: `.mat`

JSON is not the current priority.
It can be added later if needed.

### Runtime Model Handling

The three flow models are mutually exclusive:

- `1`: gas-water
- `2`: oil-water
- `3`: multi-component

The GUI should only show the active flow model's parameters.
Inactive model parameters should not be shown or used during runtime.

Current GUI simplifications now fixed in code:

- `modelflag` is no longer exposed; runtime always uses `1`.
- fracture input now uses only `FractureInput` / `fracture.input_content`
- `FractureInputStyle`, `FractureLines`, `FractureHeights`, and `FlowBarrierFlags` are no longer part of the active editable workflow

## What Has Been Completed

## 1. Parameter extraction and organization

The repository has been reviewed across:

- all 7 example case folders
- `main1.m`
- `GridProp_pre.m`
- `grid_discretization_SP_model.m`
- `grid_discretization_DP_model.m`
- `gas_water_flow.m`
- `oil_water_flow.m`
- `multi_component_flow.m`
- solver entry and main runtime functions

Completed documents:

- [`gui_parameter_plan.md`](C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305\docs\gui_parameter_plan.md)
- [`case_template_summary.md`](C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305\docs\case_template_summary.md)
- [`parameter_registry.md`](C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305\docs\parameter_registry.md)

These already cover:

- overall GUI architecture
- 7-case summary
- field-level parameter registry
- separation of editable parameters and derived runtime fields

## 2. Unified config skeleton

Created:

- [`create_empty_config.m`](C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305\gui_support\config\create_empty_config.m)

Current config structure includes:

- `meta`
- `model`
- `grid`
- `fracture`
- `discretization`
- `flow`
- `initial`
- `wells`
- `schedule`
- `solver`
- `output`

It now includes all major editable parameter groups identified so far.

## 3. Config and result MAT import/export helpers

Created:

- [`load_config_mat.m`](C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305\gui_support\config\load_config_mat.m)
- [`save_config_mat.m`](C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305\gui_support\config\save_config_mat.m)
- [`load_results_mat.m`](C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305\gui_support\results\load_results_mat.m)
- [`save_results_mat.m`](C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305\gui_support\results\save_results_mat.m)

## 4. Unified runtime entry point

Created:

- [`run_case.m`](C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305\gui_support\runtime\run_case.m)

This is now the intended runtime entry point instead of calling each case's `main1.m` directly.

Current status:

- grid preprocessing is routed through unified config
- fracture inputs are routed through unified config
- well and schedule setup are routed through unified config
- solver invocation is routed through unified config
- all three `flow_model` branches are now supported through the unified runtime path

## 5. First template support

Created:

- [`load_case_template.m`](C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305\gui_support\templates\load_case_template.m)
- [`load_case_template_case01.m`](C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305\gui_support\templates\load_case_template_case01.m)

Current template coverage:

- `case01`

This is enough to validate the unified config and runtime direction, but not yet enough for final GUI delivery.

## 6. App Designer direction clarified

Important conclusion:

- a pure `.m` app class is not the right final form for this project if the user wants to edit the GUI in MATLAB App Designer
- the final GUI should be built as a real `.mlapp`
- the current recommended workflow is:
  - manually draw the layout in App Designer
  - keep stable component names
  - then bind code to those components

## What Still Needs To Be Done

## 1. Draw the real `.mlapp` interface

This is the next main task.

Need to complete:

- top toolbar
- all main tabs
- model-specific sub-tabs or dynamic sections
- all editable controls
- result page layout

The drawing guide has been prepared conceptually, but the actual `.mlapp` still needs to be built manually in App Designer.

## 2. Bind `.mlapp` code to existing backend

After the UI is drawn, code still needs to be connected for:

- startup default config loading
- template switching
- config import/export
- result import/export
- reading values from controls into `config`
- writing `config` back into controls
- calling `run_case(config)`
- refreshing result plots

## 3. Expand template coverage

Currently only `case01` has a template loader.

Still needed:

- `case02`
- `case03`
- `case04`
- `case05`
- `case06`
- `case07`

These should eventually all become presets in the GUI.

## 4. Strengthen flow-model config coverage

The unified runtime path now supports all three model branches, but more practical work is still needed:

- make sure default template values are complete for each model
- validate that GUI fields map cleanly to backend config fields
- ensure inactive model fields do not interfere with execution

## 5. Improve editing experience for complex parameters

Right now, many large arrays or nested cell structures are still best represented as text expressions.
This is acceptable for early integration but not ideal for end users.

Likely future upgrades:

- use `UITable` for well definitions
- use `UITable` for schedules
- use `UITable` for fracture engineering input
- use dedicated table editors for relperm/PVT/adsorption data

## 6. Results page enhancement

The final result page should support:

- summary text
- well response curves
- Newton-vs-time or runtime diagnostics
- 2D and 3D plots
- selected existing post-processing functions

This is only partially addressed so far.

## Hard Parts

## 1. Parameters are not only in `main1.m`

This is the biggest structural difficulty.

Important parameters are scattered across:

- case `main1.m`
- grid preprocessing files
- SP/DP discretization files
- physics setup files
- solver-related helper files

This makes GUI extraction error-prone if only entry scripts are inspected.

## 2. Same function names appear in multiple case folders

Several case folders contain same-named files such as:

- `grid_discretization_SP_model.m`
- `multi_component_flow.m`

This means runtime path resolution can break if the working directory or MATLAB path is not controlled carefully.

The current backend addresses this by resolving case folders explicitly before running.

## 3. MATLAB App Designer is not Qt-style UI-file driven

Unlike Qt `.ui`, MATLAB `.mlapp` is not a simple open text UI definition format.
This means:

- generating App Designer GUI purely by external text editing is unreliable
- manual drawing inside App Designer is the safer workflow

## 4. Complex data entry is awkward in basic controls

Several parameters are naturally tabular or nested:

- fracture engineering input
- well definitions
- well schedules
- relperm tables
- adsorption tables

These need careful component choice.
If handled with only `TextArea`, the app will work but will not be user-friendly.

## 5. Encoding and Chinese path issues

Some files and folders contain Chinese names.
Some comments also appear to have encoding issues.

Risks:

- MATLAB string/path handling may be fine, but external tooling and generated code may display garbage text
- hardcoding such paths in generated code is risky

ASCII-safe identifiers and runtime folder resolution are preferred where possible.

## Easy-To-Break Areas

## 1. Component naming drift

If the `.mlapp` component names are changed casually after backend code is written, callbacks and data binding will break quickly.

Recommendation:

- finalize component names early
- keep names stable

## 2. Array/cell parsing from UI text

If text areas are used for MATLAB expressions, malformed input can break parsing.

Examples:

- missing brackets
- malformed cell arrays
- inconsistent row widths

Recommendation:

- use text areas only as an intermediate step
- replace key inputs with `UITable` later

## 3. Flow-model mutual exclusivity

Gas-water, oil-water, and multi-component are mutually exclusive.
If the GUI keeps unrelated fields visible and active, users may edit values that are silently ignored or accidentally used.

Recommendation:

- show only the active model section
- hide or disable the others

## 4. Schedule and well table consistency

The solver expects consistent relations among:

- `well1`
- `welloc`
- `well2`
- `well_schedules`
- `time`
- `dtmin`
- `dtmax`

If the user edits one without updating the others, runtime errors are likely.

## 5. Case-specific discretization assumptions

Case 1 includes irregular boundary polygon logic.
Case 3 uses DP-specific fields.
Other cases use different rock defaults.

If the GUI over-generalizes too early, it may hide case-specific assumptions that are required for correct runs.

## Recommended Next Step

The highest-value next step is:

1. manually build the `.mlapp` layout in App Designer
2. keep component names fixed
3. then connect each page to the existing backend functions and config structure

That is the safest path to a maintainable App Designer application.