# 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:

```matlab
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.