3D_EDFM_SIM-X/docs/gui_parameter_plan.md

GUI Parameter And Run Architecture

Decision

Use MATLAB struct as the primary runtime and persistence format.

Reasons:

• App Designer works naturally with nested struct data.
• Existing solver code already expects MATLAB variables and structs, not object models.
• struct avoids unnecessary conversion while the GUI is being built.
• JSON can still be added later as an optional export/import layer.

Recommended flow:

1. Load a case template into config as a MATLAB struct.
2. Let the GUI edit config.
3. Save or load config directly as MATLAB data first.
4. Convert config into solver inputs through a single entry point later: run_case(config).

Unified Config Layout

The GUI should be built around the following top-level fields:

config.meta
config.model
config.grid
config.fracture
config.discretization
config.flow
config.initial
config.wells
config.schedule
config.solver
config.output

Part Mapping

The existing main1.m scripts are structurally consistent and map well to the GUI:

1. model: model selection
2. grid: matrix grid definition
3. fracture: fracture input and geometry
4. discretization: SP/DP discretization and medium setup
5. flow + initial: flow model, PVT, relative permeability, initial state
6. wells + schedule: wells, perforations, stage schedule
7. solver: nonlinear and timestep controls
8. output: run execution and result presentation

Parameter Layers

The previous inventory mixed together direct inputs and fields created during preprocessing. The GUI should distinguish them explicitly.

Layer A: Editable Input Parameters

These are the parameters the GUI should expose directly or through advanced panels.

Layer B: Derived Or Runtime Fields

These are generated by preprocessing, discretization, solver assembly, or postprocessing. They should usually be displayed or logged, but not edited directly.

Core Parameter Inventory

This is the revised first-pass grouping of parameters already identified in the repository.

meta

• case_name
• case_id
• description
• source_case_folder
• created_from_template
• version

model

• modelflag
• grid_model
• flow_model

Known values:

• modelflag: currently fixed to classical EDFM in all 7 examples
• grid_model: 1 single-medium, 2 dual-medium
• flow_model: 1 gas-water, 2 oil-water, 3 multi-component

grid

Editable inputs:

• dx
• dy
• dz
• nx
• ny
• nz
• NTG

Derived by GridProp_pre and later preprocessing:

• coordinates
• nodes
• nP
• nmc
• dxv
• dyv
• dzv
• vm
• zm
• xrao
• yrao
• zrao
• cell_mid_coords

Important correction:

• boundary is not defined in GridProp_pre.m.
• In case 1 it is defined in grid_discretization_SP_model.m.
• This means geometric grid size and reservoir validity boundary are separate parameter groups and should not be merged.

fracture

• input_style
• input_content
• f
• fellip
• fractureLines
• fractureHeights
• flowBarrierFlags
• frac_information
• nf

Observed input modes:

• Engineering input table
• Vector input
• 2D line input
• Reserved .fab import mode

discretization

Editable inputs:

• grid_model
• boundary
• invalid_layer
• valid_grids generation rule
• matrix permeability definition rule
• matrix porosity definition rule
• matrix reference pressure prpor
• matrix compressibility cpor
• rock density rock_density
• fracture permeability Kf
• fracture aperture Wf
• fracture porosity Porf
• fracture reference pressure prporf
• fracture compressibility cporf
• stress_factor_fracture
• stress_factor_matrix
• stress_factor_ref_pressure
• dual-medium only:
  • kx_matrixLayer
  • ky_matrixLayer
  • kz_matrixLayer
  • pori_matrixLayer
  • sigma

Observed editable rock-property expressions in current cases:

• case 1 SP:
  • polygon boundary
  • kx/ky/kz as spatial functions of cell_mid_coords
  • pori as spatial function of cell_mid_coords
• cases 2/4/6:
  • constant matrix properties
  • invalid_layer controls inactive layers
• cases 5/7:
  • constant matrix properties, different values from cases 2/4/6
• case 3 DP:
  • fracture-layer permeability set
  • matrix-layer permeability set
  • matrix-layer porosity
  • shape factor sigma

Derived fields:

• fracture-matrix discretization result
• fracture-fracture discretization result
• EDFM connection data
• operator generation inputs for OperatorRS
• runtime fields added onto r, including rock_density, valid_grids, stress-factor fields, and dual-medium derived fields

flow

Shared categories:

• phase density
• reference pressure
• formation volume factor
• compressibility
• viscosity
• viscosity-pressure coefficient
• capillary pressure switch
• non-Darcy coefficient
• threshold pressure gradient
• matrix relative permeability table
• fracture relative permeability table

Additional note:

• Many of these are hidden inside helper files such as gas_water_flow.m, oil_water_flow.m, and multi_component_flow.m, so they must be treated as editable physics parameters even though they are not visible in main1.m.

Gas-water specific:

• gas_prop.VL
• gas_prop.PL
• gas_prop.Kn
• gas_prop.Kn_modified_factor
• gas_prop.beta_non_Darcy_flow
• density_g_sc
• gas_model
• gas PVT table or generated PVT parameters

Oil-water specific:

• density_o_sc
• oil_model
• oil PVT table or generated PVT parameters

Multi-component specific:

• Ds
• Db
• adsorption table c_ca_table
• chemistry parameters R, Vm, Temperature, chemistry_cof
• dynamic relative permeability tables cs_Nc, kr_nosurf, kr_surf, PC
• fracture counterparts of the same tables
• number_state_variables

initial

Gas-water and oil-water:

• P
• Sw

Multi-component:

• P
• Sw
• Cs
• Cb

wells

Conventional well definition:

• well1
• well name
• perforation count
• perforation grid indices
• wellbore radius
• skin
• well type

Fracture-well definition:

• num_fracture_wells
• welloc
• perfnum
• well2

Combined runtime well structure:

• Wellc

schedule

• number_phases
• well_schedules
• time
• dtmax
• dtmin

Per-row schedule fields observed:

• well name
• well state
• well role
• control mode
• target value 1
• target value 2
• optional Cs_inj
• optional Cb_inj

solver

• yitap
• yitas
• omega
• Nmax
• epsave
• epsmax

output

Runtime outputs observed:

• Times
• OutputRs
• Wellpara
• trun

Useful progress fields for the future GUI:

• current stage index
• current simulation time
• current dt
• Newton iteration count
• cumulative linear solve time
• cumulative Jacobian assembly time

Preset Strategy

The seven example folders should be treated as presets, not as independent long-term entry points.

Recommended future structure:

• load_case_template(1) ... load_case_template(7)
• each template returns a complete config
• GUI edits the config
• run_case(config) executes the solver

This avoids binding the GUI to seven different hard-coded scripts.

Run Page Scope

Pause and abort are explicitly deferred for now.

Current target for the run page:

• show active case name
• show active stage
• show current simulation time
• show current timestep
• show Newton count
• show text log
• optionally plot selected well response during run

The existing solver already prints progress with fprintf, but the proper GUI solution will be to add a progress callback later.

File-Level Sources Confirmed So Far

Primary input sources already confirmed:

• main1.m
• GridProp_pre.m
• grid_discretization_SP_model.m
• grid_discretization_DP_model.m
• preprocess_heterogeneous.m
• gas_water_flow.m
• oil_water_flow.m
• multi_component_flow.m

This matters because not all user-facing parameters live in main1.m. The parameter registry must therefore be built from the full call chain, not from entry scripts only.

Next Implementation Steps

1. Build a complete field-level parameter registry file from the 7 case folders.
2. Keep create_empty_config as the primary configuration skeleton.
3. Use run_case(config) as the single runtime entry point for all three flow models.
4. Build App Designer pages around model-specific parameter panels.

Runtime Status

Current runtime direction:

• run_case(config) is now the unified execution entry.
• flow_model is treated as mutually exclusive.
• GUI should only show the active model's parameter set.
• Non-active model parameters should remain hidden and unused.