Quick Start
===========

Your First Analysis
-------------------

Create a new Python file to run a quick analysis:

.. code-block:: python

   from pyhnhtools import load_input, run_backwater
   
   # Load a model from JSON
   model = load_input('example_model.json')
   
   # Run the steady-state analysis
   results = run_backwater(model)
   
   # Access results
   print(f"Water surface elevation: {results.wse}")
   print(f"Velocity: {results.velocity}")

Model File Format
-----------------

The input JSON file should contain:

.. code-block:: json

   {
     "reach_name": "Example Reach",
     "discharge": 500.0,
     "manning_n": 0.035,
     "cross_sections": [
       {
         "station": 0.0,
         "elevation": 100.0,
         "coordinates": [[0, 100], [10, 105], [20, 100]]
       },
       {
         "station": 100.0,
         "elevation": 99.5,
         "coordinates": [[0, 99.5], [10, 104.5], [20, 99.5]]
       }
     ]
   }

Using the GUI
-------------

For interactive model setup and visualization:

.. code-block:: bash

   python -m pyhnhtools.gui.app

The GUI provides:

- Graphical model creation and editing
- Interactive cross-section editing
- Real-time plot visualization
- Scenario management
- File import/export

Python API Overview
-------------------

Core Functions
^^^^^^^^^^^^^^

**load_input(filepath)**
    Load a model from JSON file.

    Args:
        filepath (str): Path to JSON model file

    Returns:
        ModelInput: Model object

**run_backwater(model, output_csv=None)**
    Run standard step 1D analysis.

    Args:
        model (ModelInput): Input model
        output_csv (str, optional): Output CSV filepath

    Returns:
        Results: Analysis results object

Data Classes
^^^^^^^^^^^^

**ModelInput**
    Container for model data.

    Attributes:
        reach_name (str): Name of reach
        discharge (float): Flow in cubic feet per second
        manning_n (float): Manning's roughness coefficient
        cross_sections (list): List of CrossSection objects

**CrossSection**
    Cross-section geometry and elevation.

    Attributes:
        station (float): Distance along reach
        elevation (float): Invert elevation
        coordinates (list): [[x1, z1], [x2, z2], ...] format

**Results**
    Output from solver.

    Attributes:
        wse (list): Water surface elevation at each section
        velocity (list): Velocity at each section
        profile (dict): Complete profile data

Common Workflows
----------------

Batch Analysis
^^^^^^^^^^^^^^

Run multiple discharge scenarios:

.. code-block:: python

   from pyhnhtools import load_input, run_backwater
   
   model = load_input('base_model.json')
   
   discharges = [100, 250, 500, 1000]
   results_dict = {}
   
   for Q in discharges:
       model.discharge = Q
       results = run_backwater(model)
       results_dict[Q] = results

Parameter Sensitivity
^^^^^^^^^^^^^^^^^^^^^

Evaluate Manning's n sensitivity:

.. code-block:: python

   from pyhnhtools import load_input, run_backwater
   
   model = load_input('model.json')
   n_values = [0.025, 0.035, 0.045, 0.055]
   
   for n in n_values:
       model.manning_n = n
       results = run_backwater(model)
       print(f"n={n}: WSE={results.wse}")

Next Steps
----------

- :doc:`gui_tutorial` - Learn the interactive GUI
- :doc:`../user_guide/architecture` - Understand the system architecture
- :doc:`../user_guide/std_step_1d` - Deep dive into solver
- :doc:`../api/core` - Complete API reference