Initial commit

skills/fluidsim/references/parameters.md

@@ -0,0 +1,198 @@
+# Parameter Configuration
+
+## Parameters Object
+
+The `Parameters` object is hierarchical and organized into logical groups. Access using dot notation:
+
+```python
+params = Simul.create_default_params()
+params.group.subgroup.parameter = value
+```
+
+## Key Parameter Groups
+
+### Operators (`params.oper`)
+
+Define domain and resolution:
+
+```python
+params.oper.nx = 256  # number of grid points in x
+params.oper.ny = 256  # number of grid points in y
+params.oper.nz = 128  # number of grid points in z (3D only)
+
+params.oper.Lx = 2 * pi  # domain length in x
+params.oper.Ly = 2 * pi  # domain length in y
+params.oper.Lz = pi      # domain length in z (3D only)
+
+params.oper.coef_dealiasing = 2./3.  # dealiasing cutoff (default 2/3)
+```
+
+**Resolution guidance**: Use powers of 2 for optimal FFT performance (128, 256, 512, 1024, etc.)
+
+### Physical Parameters
+
+#### Viscosity
+
+```python
+params.nu_2 = 1e-3  # Laplacian viscosity (negative Laplacian)
+params.nu_4 = 0     # hyperviscosity (optional)
+params.nu_8 = 0     # hyper-hyperviscosity (very high wavenumber damping)
+```
+
+Higher-order viscosity (`nu_4`, `nu_8`) damps high wavenumbers without affecting large scales.
+
+#### Stratification (Stratified Solvers)
+
+```python
+params.N = 1.0  # Brunt-Väisälä frequency (buoyancy frequency)
+```
+
+#### Rotation (Shallow Water)
+
+```python
+params.f = 1.0  # Coriolis parameter
+params.c2 = 10.0  # squared phase velocity (gravity wave speed)
+```
+
+### Time Stepping (`params.time_stepping`)
+
+```python
+params.time_stepping.t_end = 10.0  # simulation end time
+params.time_stepping.it_end = 100  # or maximum iterations
+
+params.time_stepping.deltat0 = 0.01  # initial time step
+params.time_stepping.USE_CFL = True  # adaptive CFL-based time step
+params.time_stepping.CFL = 0.5  # CFL number (if USE_CFL=True)
+
+params.time_stepping.type_time_scheme = "RK4"  # or "RK2", "Euler"
+```
+
+**Recommended**: Use `USE_CFL=True` with `CFL=0.5` for adaptive time stepping.
+
+### Initial Fields (`params.init_fields`)
+
+```python
+params.init_fields.type = "noise"  # initialization method
+```
+
+**Available types**:
+- `"noise"`: Random noise
+- `"dipole"`: Vortex dipole
+- `"vortex"`: Single vortex
+- `"taylor_green"`: Taylor-Green vortex
+- `"from_file"`: Load from file
+- `"in_script"`: Define in script
+
+#### From File
+
+```python
+params.init_fields.type = "from_file"
+params.init_fields.from_file.path = "path/to/state_file.h5"
+```
+
+#### In Script
+
+```python
+params.init_fields.type = "in_script"
+
+# Define initialization after creating sim
+sim = Simul(params)
+
+# Access state fields
+vx = sim.state.state_phys.get_var("vx")
+vy = sim.state.state_phys.get_var("vy")
+
+# Set fields
+X, Y = sim.oper.get_XY_loc()
+vx[:] = np.sin(X) * np.cos(Y)
+vy[:] = -np.cos(X) * np.sin(Y)
+
+# Run simulation
+sim.time_stepping.start()
+```
+
+### Output Settings (`params.output`)
+
+#### Output Directory
+
+```python
+params.output.sub_directory = "my_simulation"
+```
+
+Directory created within `$FLUIDSIM_PATH` or current directory.
+
+#### Save Periods
+
+```python
+params.output.periods_save.phys_fields = 1.0  # save fields every 1.0 time units
+params.output.periods_save.spectra = 0.5      # save spectra
+params.output.periods_save.spatial_means = 0.1  # save spatial averages
+params.output.periods_save.spect_energy_budg = 0.5  # spectral energy budget
+```
+
+Set to `0` to disable a particular output type.
+
+#### Print Control
+
+```python
+params.output.periods_print.print_stdout = 0.5  # print status every 0.5 time units
+```
+
+#### Online Plotting
+
+```python
+params.output.periods_plot.phys_fields = 2.0  # plot every 2.0 time units
+
+# Must also enable the output module
+params.output.ONLINE_PLOT_OK = True
+params.output.phys_fields.field_to_plot = "vorticity"  # or "vx", "vy", etc.
+```
+
+### Forcing (`params.forcing`)
+
+Add forcing terms to maintain energy:
+
+```python
+params.forcing.enable = True
+params.forcing.type = "tcrandom"  # time-correlated random forcing
+
+# Forcing parameters
+params.forcing.nkmax_forcing = 5  # maximum forced wavenumber
+params.forcing.nkmin_forcing = 2  # minimum forced wavenumber
+params.forcing.forcing_rate = 1.0  # energy injection rate
+```
+
+**Common forcing types**:
+- `"tcrandom"`: Time-correlated random forcing
+- `"proportional"`: Proportional forcing (maintains specific spectrum)
+- `"in_script"`: Custom forcing defined in script
+
+## Parameter Safety
+
+The Parameters object raises `AttributeError` when accessing non-existent parameters:
+
+```python
+params.nu_2 = 1e-3  # OK
+params.nu2 = 1e-3   # ERROR: AttributeError
+```
+
+This prevents typos that would be silently ignored in text-based configuration files.
+
+## Viewing All Parameters
+
+```python
+# Print all parameters
+params._print_as_xml()
+
+# Get as dictionary
+param_dict = params._make_dict()
+```
+
+## Saving Parameter Configuration
+
+Parameters are automatically saved with simulation output:
+
+```python
+params._save_as_xml("simulation_params.xml")
+params._save_as_json("simulation_params.json")
+```