@saibolla/ada 0.1.2

package/skills/fluidsim/references/output_analysis.md

@@ -0,0 +1,283 @@
+# Output and Analysis
+
+## Output Types
+
+FluidSim automatically saves several types of output during simulations.
+
+### Physical Fields
+
+**File format**: HDF5 (`.h5`)
+
+**Location**: `simulation_dir/state_phys_t*.h5`
+
+**Contents**: Velocity, vorticity, and other physical space fields at specific times
+
+**Access**:
+```python
+sim.output.phys_fields.plot()
+sim.output.phys_fields.plot("vorticity")
+sim.output.phys_fields.plot("vx")
+sim.output.phys_fields.plot("div")  # check divergence
+
+# Save manually
+sim.output.phys_fields.save()
+
+# Get data
+vorticity = sim.state.state_phys.get_var("rot")
+```
+
+### Spatial Means
+
+**File format**: Text file (`.txt`)
+
+**Location**: `simulation_dir/spatial_means.txt`
+
+**Contents**: Volume-averaged quantities vs time (energy, enstrophy, etc.)
+
+**Access**:
+```python
+sim.output.spatial_means.plot()
+
+# Load from file
+from fluidsim import load_sim_for_plot
+sim = load_sim_for_plot("simulation_dir")
+sim.output.spatial_means.load()
+spatial_means_data = sim.output.spatial_means
+```
+
+### Spectra
+
+**File format**: HDF5 (`.h5`)
+
+**Location**: `simulation_dir/spectra_*.h5`
+
+**Contents**: Energy and enstrophy spectra vs wavenumber
+
+**Access**:
+```python
+sim.output.spectra.plot1d()  # 1D spectrum
+sim.output.spectra.plot2d()  # 2D spectrum
+
+# Load spectra data
+spectra = sim.output.spectra.load2d_mean()
+```
+
+### Spectral Energy Budget
+
+**File format**: HDF5 (`.h5`)
+
+**Location**: `simulation_dir/spect_energy_budg_*.h5`
+
+**Contents**: Energy transfer between scales
+
+**Access**:
+```python
+sim.output.spect_energy_budg.plot()
+```
+
+## Post-Processing
+
+### Loading Simulations for Analysis
+
+#### Fast Loading (Read-Only)
+
+```python
+from fluidsim import load_sim_for_plot
+
+sim = load_sim_for_plot("simulation_dir")
+
+# Access all output types
+sim.output.phys_fields.plot()
+sim.output.spatial_means.plot()
+sim.output.spectra.plot1d()
+```
+
+Use this for quick visualization and analysis. Does not initialize full simulation state.
+
+#### Full State Loading
+
+```python
+from fluidsim import load_state_phys_file
+
+sim = load_state_phys_file("simulation_dir/state_phys_t10.000.h5")
+
+# Can continue simulation
+sim.time_stepping.start()
+```
+
+### Visualization Tools
+
+#### Built-in Plotting
+
+FluidSim provides basic plotting through matplotlib:
+
+```python
+# Physical fields
+sim.output.phys_fields.plot("vorticity")
+sim.output.phys_fields.animate("vorticity")
+
+# Time series
+sim.output.spatial_means.plot()
+
+# Spectra
+sim.output.spectra.plot1d()
+```
+
+#### Advanced Visualization
+
+For publication-quality or 3D visualization:
+
+**ParaView**: Open `.h5` files directly
+```bash
+paraview simulation_dir/state_phys_t*.h5
+```
+
+**VisIt**: Similar to ParaView for large datasets
+
+**Custom Python**:
+```python
+import h5py
+import matplotlib.pyplot as plt
+
+# Load field manually
+with h5py.File("state_phys_t10.000.h5", "r") as f:
+    vx = f["state_phys"]["vx"][:]
+    vy = f["state_phys"]["vy"][:]
+
+# Custom plotting
+plt.contourf(vx)
+plt.show()
+```
+
+## Analysis Examples
+
+### Energy Evolution
+
+```python
+from fluidsim import load_sim_for_plot
+import matplotlib.pyplot as plt
+
+sim = load_sim_for_plot("simulation_dir")
+df = sim.output.spatial_means.load()
+
+plt.figure()
+plt.plot(df["t"], df["E"], label="Kinetic Energy")
+plt.xlabel("Time")
+plt.ylabel("Energy")
+plt.legend()
+plt.show()
+```
+
+### Spectral Analysis
+
+```python
+sim = load_sim_for_plot("simulation_dir")
+
+# Plot energy spectrum
+sim.output.spectra.plot1d(tmin=5.0, tmax=10.0)  # average over time range
+
+# Get spectral data
+k, E_k = sim.output.spectra.load1d_mean(tmin=5.0, tmax=10.0)
+
+# Check for power law
+import numpy as np
+log_k = np.log(k)
+log_E = np.log(E_k)
+# fit power law in inertial range
+```
+
+### Parametric Study Analysis
+
+When running multiple simulations with different parameters:
+
+```python
+import os
+import pandas as pd
+from fluidsim import load_sim_for_plot
+
+# Collect results from multiple simulations
+results = []
+for sim_dir in os.listdir("simulations"):
+    if not os.path.isdir(f"simulations/{sim_dir}"):
+        continue
+
+    sim = load_sim_for_plot(f"simulations/{sim_dir}")
+
+    # Extract key metrics
+    df = sim.output.spatial_means.load()
+    final_energy = df["E"].iloc[-1]
+
+    # Get parameters
+    nu = sim.params.nu_2
+
+    results.append({
+        "nu": nu,
+        "final_energy": final_energy,
+        "sim_dir": sim_dir
+    })
+
+# Analyze results
+results_df = pd.DataFrame(results)
+results_df.plot(x="nu", y="final_energy", logx=True)
+```
+
+### Field Manipulation
+
+```python
+sim = load_sim_for_plot("simulation_dir")
+
+# Load specific time
+sim.output.phys_fields.set_of_phys_files.update_times()
+times = sim.output.phys_fields.set_of_phys_files.times
+
+# Load field at specific time
+field_file = sim.output.phys_fields.get_field_to_plot(time=5.0)
+vorticity = field_file.get_var("rot")
+
+# Compute derived quantities
+import numpy as np
+vorticity_rms = np.sqrt(np.mean(vorticity**2))
+vorticity_max = np.max(np.abs(vorticity))
+```
+
+## Output Directory Structure
+
+```
+simulation_dir/
+├── params_simul.xml         # Simulation parameters
+├── stdout.txt               # Standard output log
+├── state_phys_t*.h5         # Physical fields at different times
+├── spatial_means.txt        # Time series of spatial averages
+├── spectra_*.h5            # Spectral data
+├── spect_energy_budg_*.h5  # Energy budget data
+└── info_solver.txt         # Solver information
+```
+
+## Performance Monitoring
+
+```python
+# During simulation, check progress
+sim.output.print_stdout.complete_timestep()
+
+# After simulation, review performance
+sim.output.print_stdout.plot_deltat()  # plot time step evolution
+sim.output.print_stdout.plot_clock_times()  # plot computation time
+```
+
+## Data Export
+
+Convert fluidsim output to other formats:
+
+```python
+import h5py
+import numpy as np
+
+# Export to numpy array
+with h5py.File("state_phys_t10.000.h5", "r") as f:
+    vx = f["state_phys"]["vx"][:]
+    np.save("vx.npy", vx)
+
+# Export to CSV
+df = sim.output.spatial_means.load()
+df.to_csv("spatial_means.csv", index=False)
+```

package/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")
+```

package/skills/fluidsim/references/simulation_workflow.md

@@ -0,0 +1,172 @@
+# Simulation Workflow
+
+## Standard Workflow
+
+Follow these steps to run a fluidsim simulation:
+
+### 1. Import Solver
+
+```python
+from fluidsim.solvers.ns2d.solver import Simul
+
+# Or use dynamic import
+import fluidsim
+Simul = fluidsim.import_simul_class_from_key("ns2d")
+```
+
+### 2. Create Default Parameters
+
+```python
+params = Simul.create_default_params()
+```
+
+This returns a hierarchical `Parameters` object containing all simulation settings.
+
+### 3. Configure Parameters
+
+Modify parameters as needed. The Parameters object prevents typos by raising `AttributeError` for non-existent parameters:
+
+```python
+# Domain and resolution
+params.oper.nx = 256  # grid points in x
+params.oper.ny = 256  # grid points in y
+params.oper.Lx = 2 * pi  # domain size x
+params.oper.Ly = 2 * pi  # domain size y
+
+# Physical parameters
+params.nu_2 = 1e-3  # viscosity (negative Laplacian)
+
+# Time stepping
+params.time_stepping.t_end = 10.0  # end time
+params.time_stepping.deltat0 = 0.01  # initial time step
+params.time_stepping.USE_CFL = True  # adaptive time step
+
+# Initial conditions
+params.init_fields.type = "noise"  # or "dipole", "vortex", etc.
+
+# Output settings
+params.output.periods_save.phys_fields = 1.0  # save every 1.0 time units
+params.output.periods_save.spectra = 0.5
+params.output.periods_save.spatial_means = 0.1
+```
+
+### 4. Instantiate Simulation
+
+```python
+sim = Simul(params)
+```
+
+This initializes:
+- Operators (FFT, differential operators)
+- State variables (velocity, vorticity, etc.)
+- Output handlers
+- Time stepping scheme
+
+### 5. Run Simulation
+
+```python
+sim.time_stepping.start()
+```
+
+The simulation runs until `t_end` or specified number of iterations.
+
+### 6. Analyze Results During/After Simulation
+
+```python
+# Plot physical fields
+sim.output.phys_fields.plot()
+sim.output.phys_fields.plot("vorticity")
+sim.output.phys_fields.plot("div")
+
+# Plot spatial means
+sim.output.spatial_means.plot()
+
+# Plot spectra
+sim.output.spectra.plot1d()
+sim.output.spectra.plot2d()
+```
+
+## Loading Previous Simulations
+
+### Quick Loading (For Plotting Only)
+
+```python
+from fluidsim import load_sim_for_plot
+
+sim = load_sim_for_plot("path/to/simulation")
+sim.output.phys_fields.plot()
+sim.output.spatial_means.plot()
+```
+
+Fast loading without full state initialization. Use for post-processing.
+
+### Full State Loading (For Restarting)
+
+```python
+from fluidsim import load_state_phys_file
+
+sim = load_state_phys_file("path/to/state_file.h5")
+sim.time_stepping.start()  # continue simulation
+```
+
+Loads complete state for continuing simulations.
+
+## Restarting Simulations
+
+To restart from a saved state:
+
+```python
+params = Simul.create_default_params()
+params.init_fields.type = "from_file"
+params.init_fields.from_file.path = "path/to/state_file.h5"
+
+# Optionally modify parameters for the continuation
+params.time_stepping.t_end = 20.0  # extend simulation
+
+sim = Simul(params)
+sim.time_stepping.start()
+```
+
+## Running on Clusters
+
+FluidSim integrates with cluster submission systems:
+
+```python
+from fluiddyn.clusters.legi import Calcul8 as Cluster
+
+# Configure cluster job
+cluster = Cluster()
+cluster.submit_script(
+    "my_simulation.py",
+    name_run="my_job",
+    nb_nodes=4,
+    nb_cores_per_node=24,
+    walltime="24:00:00"
+)
+```
+
+Script should contain standard workflow steps (import, configure, run).
+
+## Complete Example
+
+```python
+from fluidsim.solvers.ns2d.solver import Simul
+from math import pi
+
+# Create and configure parameters
+params = Simul.create_default_params()
+params.oper.nx = params.oper.ny = 256
+params.oper.Lx = params.oper.Ly = 2 * pi
+params.nu_2 = 1e-3
+params.time_stepping.t_end = 10.0
+params.init_fields.type = "dipole"
+params.output.periods_save.phys_fields = 1.0
+
+# Run simulation
+sim = Simul(params)
+sim.time_stepping.start()
+
+# Analyze results
+sim.output.phys_fields.plot("vorticity")
+sim.output.spatial_means.plot()
+```