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.

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
• case_template_summary.md
• 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

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
• save_config_mat.m
• load_results_mat.m
• save_results_mat.m

4. Unified runtime entry point

Created:

• 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
• 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.