### Install SynxFlow from source code

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/quickstart.md

Installs SynxFlow by compiling directly from its GitHub source repository. This method is primarily tested for Linux machines and requires prior installation of CMake, NVIDIA CUDA Toolkit, and a C++ compiler.

```shell
pip install git+https://github.com/SynxFlow/SynxFlow.git
```

--------------------------------

### Install SynxFlow from binary wheels

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/quickstart.md

Installs the SynxFlow library using pip from pre-built binary wheels. This method is recommended for Windows (version >= 10) and Linux systems with Python 3.9, 3.10, or 3.11, and CUDA 11.3 or newer.

```shell
pip install synxflow
```

--------------------------------

### Run SynxFlow flood simulation

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/quickstart.md

Initiates a flood simulation using the `flood.run()` method. It takes the path to the prepared case folder, obtained from the input object, as an argument to start the simulation process.

```python
flood.run(obj_in.get_case_folder())
```

--------------------------------

### Run SynxFlow Flood Simulation

Source: https://synxflow.readthedocs.io/en/latest/index.html#/quickstart

Python code to initiate a flood simulation using the 'flood.run' method. This function takes the path to the prepared case folder (obtained from the input object) as an argument, starting the main simulation process.

```Python
flood.run(obj_in.get_case_folder())
```

--------------------------------

### Prepare SynxFlow Simulation Input Files

Source: https://synxflow.readthedocs.io/en/latest/index.html#/quickstart

Python code demonstrating how to use the 'demo_input' function from 'synxflow.IO' to create an input object and generate all necessary input files for a flood simulation. This includes essential files like DEM and optional files for rainfall and landcover.

```Python
import os
from synxflow.IO.demo_functions import demo_input
obj_in = demo_input() # create input object
obj_in.write_input_files() # create all input files
```

--------------------------------

### Install SynxFlow from Binary Wheels (pip)

Source: https://synxflow.readthedocs.io/en/latest/index.html#/quickstart

Command to install the SynxFlow library using pip from pre-built binary wheels. This method is suitable for Windows and Linux systems with Python 3.9, 3.10, or 3.11, and CUDA 11.3 or newer.

```Shell
pip install synxflow
```

--------------------------------

### Install SynxFlow from Source Code (pip git)

Source: https://synxflow.readthedocs.io/en/latest/index.html#/quickstart

Command to install SynxFlow directly from its GitHub source repository using pip. This method is primarily tested for Linux machines and requires prior installation of CMake, NVIDIA CUDA Toolkit, and a C++ compiler.

```Shell
pip install git+https://github.com/SynxFlow/SynxFlow.git
```

--------------------------------

### Import SynxFlow IO package

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/quickstart.md

Imports the `IO` package from `synxflow`, which is responsible for processing input and output files required for simulations.

```python
from synxflow import IO
```

--------------------------------

### Import Core SynxFlow Modules

Source: https://synxflow.readthedocs.io/en/latest/index.html#/quickstart

Python import statements to bring the 'flood' simulation engine and the 'IO' package for input/output processing into the current script. These imports enable access to SynxFlow's core functionalities for setting up and running simulations.

```Python
from synxflow import flood
```

```Python
from synxflow import IO
```

--------------------------------

### Import SynxFlow flood simulation engine

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/quickstart.md

Imports the `flood` module from the `synxflow` package, which contains the core functionalities for running flood simulations.

```python
from synxflow import flood
```

--------------------------------

### Prepare SynxFlow simulation input files

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/quickstart.md

Demonstrates how to use the `demo_input` function within `synxflow.IO` to create an input object and automatically generate necessary input files for a simulation. These files include essential data like DEM, and optional data such as rain masks and landcover information.

```python
import os
from synxflow.IO.demo_functions import demo_input
obj_in = demo_input() # create input object
obj_in.write_input_files() # create all input files
```

--------------------------------

### Install CMake via pip

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/quickstart.md

Installs CMake using pip, which is a prerequisite for compiling SynxFlow from source code. This step is typically performed on Linux machines.

```shell
pip install cmake
```

--------------------------------

### LLM Prompt for Browsing SynxFlow API Documentation

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/LLM.rst

This prompt instructs an LLM to browse and summarize key SynxFlow documentation pages, including API references for InputModel, Boundary, Rainfall, OutputModel, and Raster, as well as tutorials and installation guides. The goal is for the LLM to learn the latest API usage and best practices before assisting with code generation.

```APIDOC
Please use your browsing capability to visit and read the following SynxFlow documentation pages and tutorials:

1. InputModel API Documentation: https://synxflow.readthedocs.io/en/latest/Modules/InputModel.html
2. Boundary API Documentation: https://synxflow.readthedocs.io/en/latest/Modules/Boundary.html
3. Rainfall API Documentation: https://synxflow.readthedocs.io/en/latest/Modules/Rainfall.html
4. OutputModel API Documentation: https://synxflow.readthedocs.io/en/latest/Modules/OutputModel.html
5. Raster API Documentation: https://synxflow.readthedocs.io/en/latest/Modules/Raster.html
6. Tutorials (practical examples of using SynxFlow): https://synxflow.readthedocs.io/en/latest/Tutorials/flood.html
7. Installation (steps to install SynxFlow): https://synxflow.readthedocs.io/en/latest/quickstart.html

After reviewing, summarise the key functionalities of SynxFlow.
```

--------------------------------

### Install SynxFlow Python Package

Source: https://synxflow.readthedocs.io/en/latest/index.html#/about

This command installs the SynxFlow library using pip, the standard Python package installer. It is the essential first step to set up the model for local use, enabling access to its functionalities.

```Shell
pip install synxflow
```

--------------------------------

### JavaScript Function Definition Example

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

Illustrates a basic JavaScript function definition with a simple return statement.

```javascript
function example() {
  return true;
}
```

--------------------------------

### Set Boundary Conditions and Display Domain Map (Python)

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

This snippet sets the boundary conditions for the simulation using a predefined list (`bound_list`) and then displays the domain map to visualize the setup. It's a crucial initial step in preparing the simulation environment.

```Python
case_input.set_boundary_condition(boundary_list=bound_list)
case_input.domain_show() # show domain map
```

--------------------------------

### API Reference for Demo Functions

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/Boundary

Documentation for functions within the 'Demo functions' module, providing examples and basic I/O operations.

```APIDOC
demo_functions:
  demo_input()
  demo_output()
  demo_raster()
  get_sample_data()
```

--------------------------------

### APIDOC: IO.indep_functions.write_times_setup

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/indep_functions

Generates a 'times_setup.dat' file. This file specifies critical timing parameters for a simulation, including start time, end time, output interval, and backup interval, all in seconds.

```APIDOC
IO.indep_functions.write_times_setup(case_folder=None, num_of_sections=1, time_values=None)
  case_folder: string (default: None)
  num_of_sections: int (default: 1)
  time_values: array or list of int/float, representing time in seconds (default: [0, 3600, 1800, 3600])
```

--------------------------------

### Install SynxFlow Python Package

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/about.md

Instructions for installing the SynxFlow library using pip, the Python package installer. This command makes the SynxFlow module available for import in Python projects.

```Shell
pip install synxflow
```

--------------------------------

### Example Usage of Landslide Simulation Engine

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Modules/engines.rst

Demonstrates how to import the `synxflow.landslide` module and execute a landslide simulation using the `run` function, checking the returned status code for success or failure.

```python
from synxflow import landslide

status = landslide.run("/path/to/landslide/work_dir")
if status == 0:
    print("Landslide simulation completed successfully!")
else:
    print("Landslide simulation encountered an error.")
```

--------------------------------

### Example Usage of Flood Simulation Engine

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Modules/engines.rst

Demonstrates how to import the `synxflow.flood` module and execute a flood simulation using the `run` function, checking the returned status code for success or failure.

```python
from synxflow import flood

status = flood.run("/path/to/flood/work_dir")
if status == 0:
    print("Flood simulation completed successfully!")
else:
    print("Flood simulation encountered an error.")
```

--------------------------------

### Writing Synxflow Input Files

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

This Python code calls the `write_input_files` method on the `case_input` object. This method is responsible for generating all necessary input files for the flood simulation engine, such as DEM, times setup, device setup, and various hydraulic parameter files, preparing the simulation environment.

```python
case_input.write_input_files()
```

--------------------------------

### Configure Simulation Boundary Conditions

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/debris

Sets up the boundary conditions for the simulation, including defining source and outlet boundary boxes, time-varying discharge values, and concentration values. It then applies these conditions to the `InputModel` and visualizes the domain to confirm the setup.

```python
flux = 600/10**6 # Flux given in cm^3/s. This converts the flux to m^3
time = 20
C_in = 0.05

sourceBoundary = np.array([[-0.025,1.025], [0.025,0.975]]) # define the boundary box at the inlet
outBoundary = np.array([[15,0], [16,2]]) #define the boundary box at the outlet
discharge_values = np.array([[0,flux],[time,flux],[time+0.1,0]])
concentration_values = np.array([[0,C_in],[time,C_in],[time+0.1,0]])
hUh_out = np.array([[0,0],[1,0]])

bound_list = [{'polyPoints': sourceBoundary, 'type': 'open', 'hU': discharge_values, 'C': concentration_values},
              { 'polyPoints': outBoundary, 'type': 'open', 'hU': hUh_out, 'h': hUh_out}]

case_input.set_boundary_condition(boundary_list = bound_list, outline_boundary = 'rigid')
case_input.domain_show()
```

--------------------------------

### API: IO.demo_functions.demo_input

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/demo_functions

Documents the `demo_input` function, which serves as a demonstration to generate a Model input object. It allows for setting example initial and boundary conditions, rainfall sources, and gauge positions based on sample data, and optionally saving a domain map.

```APIDOC
IO.demo_functions.demo_input(
  num_of_sections=1,
  set_example_inputs=True,
  figname=None,
  dpi=200,
  **kwargs
)

Description: A demonstration to generate a Model input object

Parameters:
  set_example_inputs: (True|False) if True, initial condition, boundary condition, rainfall source, and gauge postion will be set to the input object according to sample data.
  figname: (string) if given, a domain map will saved
```

--------------------------------

### InputModel Object Configuration Summary

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/debris

Displays a detailed summary of the configured `InputModel` object's properties. This includes general model information (case folder, GPU count, runtime, gauges), grid specifications (area, shape, cellsize, extent), initial conditions, boundary condition details, and rainfall parameters, providing a comprehensive overview of the simulation setup.

```APIDOC
---------------------- Model information ---------------------
case_folder : /mnt/d/Projects/synxflow-newbc/SynxFlow/docs/source/Tutorials/debris_case
birthday : 2024-08-30 23:11
num_GPU : 1
run_time : [0, 60, 10, 10]
num_gauges : 8
---------------------- Grid information ----------------------
area : [np.float64(12.950000000000003), 'm^2']
shape : (80, 620)
cellsize : [0.025, 'm']
num_cells : 20720
extent : {'left': 0.0, 'right': 15.5, 'bottom': 0.0, 'top': 2.0}
---------------------- Initial condition ---------------------
h0 : 0.0
hU0x : 0
hU0y : 0
---------------------- Boundary condition --------------------
num_boundary : 3
boundary_details : ['0. (outline) rigid, number of cells: 1394', '1. open, hU given, C given, number of cells: 2', '2. open, h given, hU given, number of cells: 118']
---------------------- Rainfall ------------------------------
num_source : 1
max : [np.int64(0), 'mm/h']
sum : [np.float64(0.0), 'mm']
average : [np.float64(0.0), 'mm/h']
spatial_res : [np.float64(4.0), 'm']
temporal_res : [np.float64(1.0), 's']
```

--------------------------------

### Define Simulation Runtime and Generate Input Files

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/landslide

This snippet sets the simulation runtime parameters, including start time, total simulation time, output interval, and backup interval. After defining the runtime, it calls `write_input_files()` to generate all necessary input files for the landslide simulation based on the configured parameters.

```python
case_input.set_runtime([0, 20, 5, 20]) # start time (s), total simulation time (s), output interval (s), back up interval (s)
case_input.write_input_files()
```

--------------------------------

### Apply Boundary Conditions and Display Domain Map

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/flood

Applies the previously defined boundary conditions to the InputModel using the 'set_boundary_condition' method. Subsequently, 'domain_show()' is called to display a map of the simulation domain, allowing for visual verification of the boundary setup.

```python
case_input.set_boundary_condition(boundary_list=bound_list)
case_input.domain_show() # show domain map
```

--------------------------------

### Install CMake for SynxFlow Source Compilation

Source: https://synxflow.readthedocs.io/en/latest/index.html#/quickstart

Command to install CMake using pip. CMake is a required dependency for compiling SynxFlow from source code, primarily on Linux machines.

```Shell
pip install cmake
```

--------------------------------

### Example: Displaying Ranks with rankshow

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/Raster

Illustrates how to use `rankshow` to visualize data in ranks, specifying figure properties, color scheme, rank breaks, and detailed legend settings.

```Python
rankshow(figname=None, figsize=None,
    dpi=200, ax=None, color='Blues',
    breaks=[0.2, 0.3, 0.5, 1, 2],
    legend_kw={'loc':'upper left', 'facecolor':None,
    'fontsize':'small', 'title':'depth(m)',
    'labelspacing':0.1},
    ytick_labelrotation=None, relocate=False, scale_ratio=1,
    alpha=1)
```

--------------------------------

### LLM Prompt for Generating SynxFlow Flood Simulation Code

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/LLM

This prompt asks an LLM to generate a sample Python code example for creating, running, and visualizing a flood simulation using SynxFlow's sample data. The expected output script should load sample data, initialize an InputModel, set up parameters, run the simulation, and visualize outputs.

```APIDOC
Please show me a sample code that creates, runs, and visualizes a flood simulation using SynxFlow’s sample data.
```

--------------------------------

### Example Usage of Debris Flow Simulation Engine

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Modules/engines.rst

Demonstrates how to import the `synxflow.debris` module and execute a debris flow simulation using the `run` function, checking the returned status code for success or failure.

```python
from synxflow import debris

status = debris.run("/path/to/debris/work_dir")
if status == 0:
    print("Debris flow simulation completed successfully!")
else:
    print("Debris flow simulation encountered an error!")
```

--------------------------------

### Set CUDAToolkit_ROOT Environment Variable

Source: https://synxflow.readthedocs.io/en/latest/index.html#/quickstart

Commands to define the CUDAToolkit_ROOT environment variable. This step may be necessary if multiple CUDA Toolkit versions are installed on your system, ensuring SynxFlow links to the correct version.

```Shell
export CUDAToolkit_ROOT=<path to your cuda directory>
```

```Shell
export CUDAToolkit_ROOT=/usr/local/cuda-11.3
```

--------------------------------

### List Sample Data Files in Synxflow

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

This Python snippet initializes the Synxflow I/O module, retrieves the path to the sample data directory using `get_sample_data()`, and then lists all files present in that directory. It demonstrates how to access the provided sample datasets for flood simulation.

```python
from synxflow import IO
import os
from synxflow.IO.demo_functions import get_sample_data
dem_file, demo_data, data_path = get_sample_data() # get the path of sample data
os.listdir(data_path)
```

--------------------------------

### Configure Simulation Runtime Parameters

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/flood

Sets the simulation's runtime parameters, including start time, end time, output interval, and backup interval. This configuration controls the total duration of the simulation and the frequency at which data is logged and saved.

```python
case_input.set_runtime([0, 7200, 900, 1800])
```

--------------------------------

### Set Synxflow Simulation Runtime and Generate Input Files

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/landslide.ipynb

Defines the simulation's time parameters, including the start time, total simulation duration, output interval, and backup interval. Following this, it generates all necessary input files required for the Synxflow model based on the configured settings.

```python
case_input.set_runtime([0, 20, 5, 20]) # start time (s), total simulation time (s), output interval (s), back up interval (s)
case_input.write_input_files()
```

--------------------------------

### Initialize Simulation Input Model with DEM in Python

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/debris.ipynb

This code initializes an `IO.InputModel` object, which serves as the primary input container for the debris flow simulation. It takes the loaded DEM data, specifies the number of sections, and defines a dedicated case folder for simulation outputs. This setup prepares the environment for defining further simulation parameters.

```python
case_folder = os.path.join(os.getcwd(), 'debris_case') # define a case folder in the current directory
case_input = IO.InputModel(DEM, num_of_sections=1, case_folder=case_folder)
```

--------------------------------

### Synxflow Independent Utility Functions API

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/Landcover

API documentation for general utility functions, including cleaning output directories, loading/saving objects, and writing device/rain source/times setup configurations. These functions provide essential support for managing data and configurations within Synxflow projects.

```APIDOC
clean_output()
load_object()
save_as_dict()
save_object()
write_device_setup()
write_rain_source()
write_times_setup()
```

--------------------------------

### SynxFlow Landslide Module API Reference

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/engines

Details the API for the `landslide` module, which provides core functionality for simulating landslide runout events using GPU acceleration. It includes a method for starting the simulation, requiring a working directory for input data and output storage.

```APIDOC
landslide.run(work_dir: str) -> int
  work_dir: The path to the working directory containing the necessary input data (e.g. terrain models, material properties) for the landslide simulation, and where outputs will be written.
  Returns: A status code where 0 indicates success and a non-zero value indicates an error.
```

--------------------------------

### Set Initial Water Depth Condition

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

Applies an initial water depth across the catchment using the `set_initial_condition` method of the `InputModel`. In this specific example, the initial depth is set to 0 meters, simulating a dry catchment before the flood event begins.

```python
case_input.set_initial_condition('h0', 0.0)
```

--------------------------------

### Execute Flood Simulation with SynxFlow Python API

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/engines

This Python example demonstrates how to use the `flood.run` method from the `synxflow` package to execute a flood simulation. It initializes the simulation with a specified working directory and checks the returned status code to confirm successful completion or identify errors.

```Python
from synxflow import flood

status = flood.run("/path/to/flood/work_dir")
if status == 0:
    print("Flood simulation completed successfully!")
else:
    print("Flood simulation encountered an error.")
```

--------------------------------

### Set CUDAToolkit_ROOT environment variable

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/quickstart.md

Defines the CUDAToolkit_ROOT environment variable to specify the path to your CUDA Toolkit installation. This is necessary if multiple CUDA versions are present on your system to ensure SynxFlow links against the correct one.

```shell
export CUDAToolkit_ROOT=<path to your cuda directory>
```

```shell
export CUDAToolkit_ROOT=/usr/local/cuda-11.3
```

--------------------------------

### Retrieve and List SynxFlow Sample Debris Flow Data

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/debris

This snippet demonstrates how to use the `synxflow.IO` module to retrieve sample debris flow data. It initializes the `IO` module, gets the path to the sample data for a 'debris' case type, and then lists the contents of the data directory to show available files like 'Erosion.txt' and 'DEM.txt'.

```Python
from synxflow import IO
import os
from synxflow.IO.demo_functions import get_sample_data
dem_file, demo_data, data_path = get_sample_data(case_type ='debris') # get the path of sample data
os.listdir(data_path)
```

--------------------------------

### Execute Landslide Simulation with SynxFlow Python API

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/engines

This Python example demonstrates how to use the `landslide.run` method from the `synxflow` package to execute a landslide runout simulation. It specifies the working directory for the simulation and evaluates the return status to determine success or failure.

```Python
from synxflow import landslide

status = landslide.run("/path/to/landslide/work_dir")
if status == 0:
    print("Landslide simulation completed successfully!")
else:
    print("Landslide simulation encountered an error.")
```

--------------------------------

### Display Model Summary (Python)

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

This code calls a method to display a comprehensive summary of the configured model. This summary provides an overview of various simulation parameters, grid information, initial conditions, and boundary conditions, useful for verification and debugging.

```Python
case_input.model_summary()
```

--------------------------------

### OpenAIModel Class API Reference

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

API documentation for the OpenAIModel class, detailing its constructor (__init__) method and its parameters.

```APIDOC
OpenAIModel:
  __init__(model_name: str, provider: str = 'openai')
    model_name: The name of the OpenAI model to use
    provider: The provider to use (defaults to 'openai')
```

--------------------------------

### OpenAIModel Class Initialization

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

Documents the `__init__` method of the `OpenAIModel` class, including its parameters `model_name` and `provider` with their respective types and descriptions. This snippet outlines how to instantiate the OpenAIModel.

```APIDOC
OpenAIModel:
  __init__(model_name: str, provider: str = 'openai')
    model_name: The name of the OpenAI model to use
    provider: The provider to use (defaults to 'openai')
```

--------------------------------

### List Sample Data Files in synxflow Demo Directory (Python)

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/flood

This Python snippet initializes the sample data environment using `synxflow.IO.demo_functions.get_sample_data()` to obtain the data directory path. It then uses `os.listdir()` to list all files present in this directory, providing an overview of the available simulation input files.

```python
from synxflow import IO
import os
from synxflow.IO.demo_functions import get_sample_data
dem_file, demo_data, data_path = get_sample_data() # get the path of sample data
os.listdir(data_path)
```

--------------------------------

### Set Runtime and Generate Solver Input Files

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/debris

Configures the simulation runtime parameters, prints a summary of the model's current configuration, retrieves data folders, and finally writes all generated input files required by the solver. This prepares the simulation for execution.

```python
case_input.set_runtime([0, 60, 10, 10])
print(case_input)

case_input.get_data_folders()
case_input.write_input_files()
```

--------------------------------

### OpenAIModel Class Initialization

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

Documents the `OpenAIModel` class, specifically its constructor `__init__`. It details the required `model_name` parameter and the optional `provider` parameter, including their types and default values.

```APIDOC
OpenAIModel:
  __init__(model_name: str, provider: str = 'openai')
    model_name: The name of the OpenAI model to use
    provider: The provider to use (defaults to 'openai')
```

--------------------------------

### IO.InputModel.get_input_filenames Method

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/InputModel

Get the input file names.

```APIDOC
IO.InputModel.get_input_filenames()
  Returns: list - a list of string giving all input filenames without
```

--------------------------------

### OpenAIModel Class Constructor Documentation

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/landslide.ipynb

Detailed documentation for the `__init__` method of the `OpenAIModel` class, outlining the `model_name` and `provider` parameters, their types, and descriptions.

```APIDOC
OpenAIModel:
  __init__(model_name: str, provider: str = 'openai')
    model_name: The name of the OpenAI model to use
    provider: The provider to use (defaults to 'openai')
```

--------------------------------

### List Sample Data Files in synxflow

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/landslide.ipynb

This Python snippet demonstrates how to access and list the sample data files provided by the `synxflow` package. It imports necessary modules, retrieves the path to the landslide sample data, and then lists the contents of that directory. This helps in understanding the available input files for the simulation.

```python
from synxflow import IO
import os
from synxflow.IO.demo_functions import get_sample_data
dem_file, demo_data, data_path = get_sample_data(case_type ='landslide') # get the path of sample data
os.listdir(data_path)
```

--------------------------------

### API: IO.InputModel.write_halo_file Method

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/InputModel

Write the overlayed cell IDs file, which is typically used in distributed computing setups.

```APIDOC
write_halo_file()
```

--------------------------------

### API: IO.InputModel.write_gauges_position Method

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/InputModel

Write the gauges position file. This version is compatible with both single and multiple GPU setups.

```APIDOC
write_gauges_position(gauges_pos=None)
  gauge_pos: (2-column numpy array) positions of gauges
```

--------------------------------

### Demo Functions API

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/Summary

Documentation for demonstration-related input/output functions within the Synxflow library.

```APIDOC
demo_input()
demo_output()
demo_raster()
get_sample_data()
```

--------------------------------

### OpenAIModel Class Initialization

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

This section details the `OpenAIModel` class constructor, `__init__`, specifying the required `model_name` and optional `provider` parameters. It outlines how to instantiate an OpenAI model within the Synxflow framework.

```APIDOC
OpenAIModel:
  __init__(model_name: str, provider: str = 'openai')
    model_name: The name of the OpenAI model to use
    provider: The provider to use (defaults to 'openai')
```

--------------------------------

### API: IO.InputModel.set_runtime Method

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/InputModel

Configure the runtime parameters of the model, including start time, end time, output interval, and backup interval.

```APIDOC
set_runtime(runtime=None)
  runtime: a list of four values representing start, end, output interval and backup interval respectively
```

--------------------------------

### Load SynxFlow Sample Landslide Data (Python)

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/landslide

This Python snippet demonstrates how to retrieve sample landslide simulation data using `synxflow.IO.demo_functions.get_sample_data`. It initializes the data path and then lists the contents of the directory, typically showing the `dem.gz` and `depth.gz` files required for the simulation.

```python
from synxflow import IO
import os
from synxflow.IO.demo_functions import get_sample_data
dem_file, demo_data, data_path = get_sample_data(case_type ='landslide') # get the path of sample data
os.listdir(data_path)
```

--------------------------------

### Get X and Y Coordinates of Raster Cells

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/Raster

Retrieves the X and Y coordinates for all cells within the raster object, returning them as a NumPy array.

```APIDOC
to_points()
  Description: Get X and Y coordinates of all raster cells
  Returns:
    numpy array: coordinates of the raster object
```

--------------------------------

### OpenAIModel Class Initialization

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

Documents the constructor for the OpenAIModel class, detailing its parameters and their purpose. This class likely serves as an interface for interacting with OpenAI models.

```APIDOC
OpenAIModel:
  __init__(model_name: str, provider: str = 'openai')
    model_name: The name of the OpenAI model to use
    provider: The provider to use (defaults to 'openai')
```

--------------------------------

### API Documentation: Independent Functions

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/index

Offers a collection of independent utility functions for cleaning output, loading/saving objects, and writing setup configurations.

```APIDOC
Independent functions:
  clean_output()
  load_object()
  save_as_dict()
  save_object()
  write_device_setup()
  write_rain_source()
  write_times_setup()
```

--------------------------------

### Independent Functions API

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/Summary

Documentation for general utility functions that operate independently, such as cleaning output, loading/saving objects, and writing device setup information.

```APIDOC
clean_output()
load_object()
save_as_dict()
save_object()
write_device_setup()
```

--------------------------------

### Execute Landslide Simulation

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/landslide

This code imports the `landslide` module from `synxflow` and initiates the landslide simulation. It calls the `run` function, passing the previously defined `case_folder` as the argument, which contains all the necessary input files for the simulation to proceed.

```python
from synxflow import landslide
landslide.run(case_folder)
```

--------------------------------

### Create Animation of Gridded Rainfall Rate

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/rainfall_processing

Creates an animation of gridded rainfall rate. Requires a mask header, start date, and duration for each frame.

```APIDOC
IO.rainfall_processing.create_animation(output_file, rain_source, mask_file, duration=0.5, **kwargs)
  Parameters:
    mask_header: (dict) header file provide georeference of rainfall mask
    start_date: a datetime object to give the initial date and time of rain
    duration: duration for each frame (seconds)
    cellsize: sclar (meter) the size of rainfall grid cells
```

--------------------------------

### Independent Functions API Reference

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/grid_show

Provides a collection of independent utility functions for tasks such as cleaning output, loading/saving objects, and writing device/time setup configurations.

```APIDOC
Module: IO.indep_functions
  Functions:
    - clean_output()
    - load_object()
    - save_as_dict()
    - save_object()
    - write_device_setup()
    - write_rain_source()
    - write_times_setup()
```

--------------------------------

### Execute Synxflow Landslide Simulation

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/landslide.ipynb

Imports the Synxflow landslide module and initiates the simulation run. The simulation uses the previously configured input files located in the specified case folder. Note that the landslide solver currently supports only single GPU execution.

```python
from synxflow import landslide
landslide.run(case_folder)
```

--------------------------------

### API: IO.InputModel.InputModelSub Class

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/InputModel

Represents an object for each section of the model, serving as a child class of `InputModel`. It manages data specific to individual sections, particularly in multi-domain setups.

```APIDOC
class IO.InputModel.InputModelSub(dem_array, header, case_folder, num_of_sections)
  dem_array: (Implicit from context)
  header: (Implicit from context)
  case_folder: (Implicit from context)
  num_of_sections: (Implicit from context)

  Attributes:
    sectionNO: the serial number of each section
    _valid_cell_subs: (tuple, int) two numpy array indicating rows and cols of valid cells on the local grid
    valid_cell_subsOnGlobal: (tuple, int) two numpy array indicating rows and cols of valid cells on the global grid
    shared_cells_id: 2-row shared Cells id on a local grid
    case_folder: input folder of each section
    _outline_cell_subs: (No description provided)
```

--------------------------------

### API Reference for Independent Utility Functions

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/Boundary

Documentation for general-purpose utility functions that are independent of specific modules, including object serialization, file cleaning, and device setup.

```APIDOC
indep_functions:
  clean_output()
  load_object()
  save_as_dict()
  save_object()
  write_device_setup()
  write_rain_source()
```

--------------------------------

### Get Spatial Rainfall Map

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/rainfall_processing

Retrieves a spatial rainfall map. Supports resampling the rain mask and choosing a calculation method (sum or mean) for each cell.

```APIDOC
IO.rainfall_processing.get_spatial_map(rain_source, rain_mask_obj, figname=None, method='sum', cellsize=None, shp_file=None, dpi=200, title=None, **kwargs)
  Parameters:
    rain_mask_obj: asc file name or Raster object for rain mask
    cellsize: resample the rain_mask to a new grid (with larger cellsize)
    method: sum|mean caculate method for each cell, sum by time or mean by time
```

--------------------------------

### Create Rainfall Rate Images

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/rainfall_processing

Generates images of rainfall rate from a rainfall time series and a mask file. Allows specifying cell size, start date, and DPI.

```APIDOC
IO.rainfall_processing.create_pictures(rain_source, mask_file, cellsize=1000, start_date=None, dpi=100, shp_file=None, **kwargs)
  Parameters:
    rain_source: a numpy array of rainfall time series, 1st column is time in seconds, other columns are rainfall intensity in m/s
    mask_file: a arc grid or a Raster object
```

--------------------------------

### Synxflow API: Demo Functions

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/engines

This section outlines functions designed for demonstrating basic input/output operations and data handling within the Synxflow framework. These functions are useful for quick tests and understanding core data interactions.

```APIDOC
demo_input()
```

```APIDOC
demo_output()
```

```APIDOC
demo_raster()
```

```APIDOC
get_sample_data()
```

--------------------------------

### OpenAIModel Class Initialization

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

Documents the `OpenAIModel` class constructor, detailing its parameters and their purpose. This class is likely used to interact with OpenAI models, providing a structured way to initialize model instances.

```APIDOC
OpenAIModel:
  __init__(model_name: str, provider: str = 'openai')
    model_name: The name of the OpenAI model to use
    provider: The provider to use (defaults to 'openai')
```

--------------------------------

### Convert Matrix Subscripts to Map Coordinates

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/spatial_analysis

Documents the `sub2map` function, which converts row and column subscripts of a matrix into corresponding X and Y map coordinate values. Subscripts are assumed to start from 0.

```APIDOC
IO.spatial_analysis.sub2map(rows, cols, header) -> X and Y coordinate values
  convert subscripts of a matrix to map coordinates rows, cols: subscripts of the data matrix, starting from 0
  Parameters:
    rows: rows in the array
    cols: cols in the array
    header: Header information for the array.
  Returns:
    X and Y coordinate values
```

--------------------------------

### Configure Simulation Runtime and Generate Input Files

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/debris.ipynb

This code sets the total simulation runtime and time steps for the SynxFlow model. It then prints the detailed model information, retrieves data folder paths, and proceeds to generate all necessary input files for the solver based on the previously defined parameters and conditions.

```python
case_input.set_runtime([0, 60, 10, 10])
print(case_input)

case_input.get_data_folders()
case_input.write_input_files()
```

--------------------------------

### API Reference: Independent Utility Functions

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/InputModel

Lists general utility functions that are independent of specific modules, including operations for cleaning output, loading/saving objects, and writing various setup configurations.

```APIDOC
IO.indep_functions:
  - clean_output()
  - load_object()
  - save_as_dict()
  - save_object()
  - write_device_setup()
  - write_rain_source()
  - write_times_setup()
```

--------------------------------

### SynxFlow Independent Utility Functions

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/index

This section provides a list of general-purpose utility functions in SynxFlow, covering operations like cleaning output, object serialization (load/save), and device/rain/time setup configurations.

```APIDOC
clean_output()
```

```APIDOC
load_object()
```

```APIDOC
save_as_dict()
```

```APIDOC
save_object()
```

```APIDOC
write_device_setup()
```

```APIDOC
write_rain_source()
```

```APIDOC
write_times_setup()
```

--------------------------------

### Display Model Summary Information

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/flood

Prints a comprehensive summary of the configured InputModel object. This output provides an overview of various model parameters such as case folder, GPU usage, runtime, grid information, initial conditions, boundary conditions, and rainfall details, useful for verification.

```python
print(case_input)
```

--------------------------------

### Initialize Raster Object with Random Array (Python)

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/Raster

Example demonstrating how to create an IO.Raster.Raster object using a randomly generated NumPy array and a custom header dictionary, then display the raster map.

```python
array = np.random.rand(10, 10)
header = {'ncols':array.shape[1], 'nrows':array.shape[0],
          'xllcorner':0, 'yllcorner':1,
          'cellsize':100, 'NODATA_value':-9999}
obj_ras = Raster(array=array, header=header)
obj_ras.mapshow() #plot map
```

--------------------------------

### OpenAIModel Class Initialization

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

Defines the `OpenAIModel` class constructor, outlining the required `model_name` and optional `provider` parameters for initializing an OpenAI model instance. The `model_name` specifies the particular OpenAI model to be used, while `provider` defaults to 'openai'.

```APIDOC
OpenAIModel:
  __init__(model_name: str, provider: str = 'openai')
    model_name: The name of the OpenAI model to use
    provider: The provider to use (defaults to 'openai')
```

--------------------------------

### Get Time Series of Average Rainfall Rate

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/rainfall_processing

Calculates and returns a time series of average rainfall rate within the model domain. Supports different calculation methods like mean, max, or min.

```APIDOC
IO.rainfall_processing.get_time_series(rain_source, rain_mask=None, start_date=None, method='mean')
  Parameters:
    method: 'mean'|'max','min','mean'method to calculate gridded rainfall over the model domain
```

--------------------------------

### Read and Display SynxFlow Grid File Output

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

This Python snippet illustrates the process of loading a grid file generated by SynxFlow using the `case_output.read_grid_file` method. After reading the data, it visualizes the content using the `mapshow()` function, providing a quick way to inspect simulation results.

```python
max_depth = case_output.read_grid_file(file_tag='h_max_7200')
max_depth.mapshow()
```

--------------------------------

### Set Initial Water Depth

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/flood

Sets the initial water depth across the catchment to 0 meters using the 'h0' parameter of the set_initial_condition method of the InputModel object. This establishes the starting water level for the simulation.

```python
case_input.set_initial_condition('h0', 0.0)
```

--------------------------------

### List Sample Data Files with Synxflow in Python

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/debris.ipynb

This Python snippet demonstrates how to initialize the Synxflow IO module and retrieve sample debris flow data. It uses the `get_sample_data` function to obtain the path to the sample data directory and then lists the contents of that directory using `os.listdir`. This helps in identifying the available data files, such as 'Erosion.txt' and 'DEM.txt', which are crucial for the simulation.

```python
from synxflow import IO
import os
from synxflow.IO.demo_functions import get_sample_data
dem_file, demo_data, data_path = get_sample_data(case_type ='debris') # get the path of sample data
os.listdir(data_path)
```

--------------------------------

### Define Flow Gauge Positions

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/debris

Specifies the locations for flow gauges within the simulation domain. This example defines eight gauges, four at the inlet and four at the outlet, using a NumPy array of normalized coordinates.

```python
case_input.set_gauges_position(np.array([[0.5, 0.95],
                                        [0.5,0.975],
                                        [0.5,1.0],
                                        [0.5,1.025],
                                        [8.5,0.95],
                                        [8.5,0.975],
                                        [8.5,1.0],
                                        [8.5,1.025]]))
```

--------------------------------

### Initialize Flood Simulation Input Model

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

Initializes an `InputModel` object, which is fundamental for setting up the flood simulation. This involves specifying the Digital Elevation Model (DEM), the number of processing units (e.g., GPUs), and the designated folder for simulation outputs. This configuration prepares the core structure for the simulation run.

```python
ngpus = 1
case_folder = os.path.join(os.getcwd(), 'flood_case') # define a case folder in the current directory
case_input = IO.InputModel(DEM, num_of_sections=ngpus, case_folder=case_folder)
```

--------------------------------

### Load and Display Raster Data

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

Loads a gzipped landcover raster file into the simulation environment using `IO.Raster` and visualizes it on a map. This initial step is crucial for incorporating geographical data into the flood model and verifying its correct loading.

```python
landcover = IO.Raster(os.path.join(data_path,'landcover.gz'))
landcover.mapshow()
```

--------------------------------

### Example: Displaying a Map with mapshow

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/Raster

Demonstrates how to use the `mapshow` function to display a map with specified figure name, size, DPI, title, colorbar, and axis rotation. Note that `ax` and `cax` are likely context-dependent variables.

```Python
mapshow(ax=ax, figname='my_fig', figsize=(6, 8), dpi=300,
    title='My map', cax=True, cax_str='Meter',
    relocate=False, scale_ratio=1000,
    ytick_labelrotation=90)
```

--------------------------------

### Synxflow API: Independent Utility Functions

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/engines

This section provides a collection of general utility functions that operate independently of specific modules. These include functions for cleaning output, loading and saving objects, and writing various setup configurations.

```APIDOC
clean_output()
```

```APIDOC
load_object()
```

```APIDOC
save_as_dict()
```

```APIDOC
save_object()
```

```APIDOC
write_device_setup()
```

```APIDOC
write_rain_source()
```

```APIDOC
write_times_setup()
```

--------------------------------

### OpenAIModel Class Initialization API

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/landslide.ipynb

Documents the `__init__` method of the `OpenAIModel` class, outlining its required `model_name` parameter and optional `provider` parameter with their respective types and descriptions. This constructor is used to instantiate an OpenAI model object.

```APIDOC
OpenAIModel:
  __init__(model_name: str, provider: str = 'openai')
    model_name: The name of the OpenAI model to use
    provider: The provider to use (defaults to 'openai')
```

--------------------------------

### Set Initial Water Depth for Simulation

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/debris

Sets the initial water depth across the catchment using the `set_initial_condition` method of the `InputModel` object. In this specific example, the initial depth ('h0') is uniformly set to 0.0 meters.

```python
case_input.set_initial_condition('h0', 0.0)
```

--------------------------------

### API Documentation: Demo Functions

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/index

This section outlines demonstration functions for basic input/output operations and raster data handling within the Synxflow library.

```APIDOC
Demo functions:
  demo_input()
  demo_output()
  demo_raster()
  get_sample_data()
```

--------------------------------

### Synxflow Demo Functions API

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/Landcover

API documentation for demonstration functions within Synxflow, including utilities for handling input, output, raster data, and retrieving sample datasets. These functions are typically used for quick testing and showcasing library capabilities.

```APIDOC
demo_input()
demo_output()
demo_raster()
get_sample_data()
```

--------------------------------

### Example: Write Grid Data to ASCII File (arcgridwrite)

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Modules/spatial_analysis

Demonstrates how to use `arcgridwrite` to save a NumPy array as an ASCII grid file, with and without compression. It initializes a sample grid and header, then calls the function twice for different compression settings.

```python
gird = np.zeros((5,10))
grid[0,:] = -9999
grid[-1,:] = -9999
header = {'ncols':10, 'nrows':5, 'xllcorner':0, 'yllcorner':0,
              'cellsize':2, 'NODATA_value':-9999}
file_name = 'example_file.asc'
arcgridwrite(file_name, array, header, compression=False)
arcgridwrite(file_name, array, header, compression=True)
```

--------------------------------

### Initialize InputModel for Flood Simulation

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/flood

Initializes the InputModel object with the Digital Elevation Model (DEM), specifies the number of GPUs, and defines the simulation's case folder. This sets up the core model environment for the flood simulation.

```python
ngpus = 1
case_folder = os.path.join(os.getcwd(), 'flood_case') # define a case folder in the current directory
case_input = IO.InputModel(DEM, num_of_sections=ngpus, case_folder=case_folder)
```

--------------------------------

### Initialize InputModel for Debris Flow Simulation

Source: https://synxflow.readthedocs.io/en/latest/index.html#/Tutorials/debris

Initializes an `InputModel` object with a Digital Elevation Model (DEM) and specifies the case folder for simulation output and the number of processing devices. This sets up the fundamental environment for the simulation.

```python
case_folder = os.path.join(os.getcwd(), 'debris_case') # define a case folder in the current directory
case_input = IO.InputModel(DEM, num_of_sections=1, case_folder=case_folder)
```

--------------------------------

### OpenAIModel Class Definition

Source: https://synxflow.readthedocs.io/en/latest/index.html#/_sources/Tutorials/flood.ipynb

Defines the OpenAIModel class, detailing its constructor and the parameters required for initialization, such as the model name and an optional provider.

```APIDOC
OpenAIModel:
  __init__(model_name: str, provider: str = 'openai')
    model_name: The name of the OpenAI model to use
    provider: The provider to use (defaults to 'openai')
```