Usage Guide
===========

Command-Line Interface (CLI)
----------------------------

ZEFIR provides a flexible command-line interface for launching different GUI applications:

**Basic Usage:**

.. code-block:: bash

   # Show all available commands
   python -m zefir --help

   # Launch the potential flow GUI (default)
   python -m zefir potentialflow

   # Show potential flow specific options
   python -m zefir potentialflow --help

**CLI Options for Potential Flow:**

.. code-block:: bash

   usage: zefir potentialflow [-h] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--fullscreen]

   Launch the potential flow visualization GUI

   options:
     -h, --help            show this help message and exit
     --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                           Set the logging level (default: INFO)
     --fullscreen          Start the GUI in fullscreen mode

**Examples:**

.. code-block:: bash

   # Launch with debug logging
   python -m zefir potentialflow --log-level DEBUG

   # Launch in fullscreen mode
   python -m zefir potentialflow --fullscreen

   # Launch with warning level logs only
   python -m zefir potentialflow --log-level WARNING

Launching the GUI Programmatically
----------------------------------

You can also launch the GUI directly from Python:

**Method 1: Using the main function**

.. code-block:: python

   from zefir.gui.potential import main
   main()

**Method 2: Creating the GUI manually**

.. code-block:: python

   from zefir.gui.potential import PotentialFlowGUI
   import sys
   from PySide6.QtWidgets import QApplication

   app = QApplication(sys.argv)
   window = PotentialFlowGUI()
   window.show()
   sys.exit(app.exec())

**Method 3: With custom logging configuration**

.. code-block:: python

   from zefir.gui.potential import PotentialFlowGUI
   from zefir.logging import configure_log, LogLevel
   import sys
   from PySide6.QtWidgets import QApplication

   # Configure logging
   configure_log(level=LogLevel.DEBUG)

   app = QApplication(sys.argv)
   window = PotentialFlowGUI()
   window.show()
   sys.exit(app.exec())

Creating Flows
--------------

1. **Add Elementary Flows**:
   - Select a flow type from the dropdown in the left panel
   - Click "Add" to create a new flow
   - Adjust parameters using the spin boxes

2. **Flow Types Available**:
   - **Uniform Flow**: Constant velocity field
   - **Source/Sink**: Radial flow from/to a point
   - **Doublet**: Dipole flow pattern
   - **Vortex**: Rotational flow around a point
   - **Power Law**: Corner flows with exponent β

3. **Positioning Flows**:
   - **Manual**: Enter x,y coordinates in the parameter panel
   - **Interactive**: Enable "Mouse Placement Mode" and click on the plot

Visualization Modes
-------------------

Switch between different visualization modes using the radio buttons in the right panel:

- **Streamlines**: Shows lines of constant stream function (ψ)
- **Potential Lines**: Shows lines of constant potential (φ)
- **Velocity Magnitude**: Color-coded plot of |V|
- **Pressure Coefficient**: Color-coded plot of Cp = 1 - (V/V∞)²

Log Console
-----------

The GUI includes an integrated log console dock panel at the bottom:

- **Level Filtering**: Use radio buttons to filter logs by level (Debug, Info, Warning, Error, Critical)
- **Color Coding**: 
  - Debug: Gray
  - Info: Blue
  - Warning: Orange
  - Error: Red
  - Critical: Dark Red
- **Monospace Font**: Easy to read log messages
- **Real-time Updates**: Logs appear as they are generated

Customization
-------------

- **Contour Levels**: Adjust the number of contour lines (10-100)
- **Grid Resolution**: Set the computational grid size (50-500 points)
- **Domain**: Default is x,y ∈ [-2, 2] (can be modified in code)

Programmatic Usage
------------------

You can also use ZEFIR programmatically:

.. code-block:: python

   from zefir.potential import UniformFlow, SourceFlow, PotentialSuperposition
   from zefir.logging import info, debug
   import numpy as np

   # Configure logging
   from zefir.logging import configure_log, LogLevel
   configure_log(level=LogLevel.DEBUG)

   info("Creating flow superposition")
   
   # Create flows
   flow = PotentialSuperposition()
   flow.append(UniformFlow((1.0, 0.0)))
   flow.append(SourceFlow(1.0, (-0.3, 0.0)))
   flow.append(SourceFlow(-1.0, (0.3, 0.0)))

   debug("Flow superposition created with %d flows", len(flow._flows))

   # Evaluate on a grid
   x = np.linspace(-2, 2, 200)
   y = np.linspace(-2, 2, 200)
   X, Y = np.meshgrid(x, y, indexing='ij')
   Z = X + 1j*Y

   # Get potential and velocity
   potential = flow(Z)
   velocity = flow.velocity(Z)

   info("Evaluated flow at %d points", Z.size)

Logging System
--------------

ZEFIR includes a centralized logging system:

**Basic Usage:**

.. code-block:: python

   from zefir.logging import info, debug, warning, error, configure_log, LogLevel

   # Configure logging
   configure_log(level=LogLevel.DEBUG)

   # Log messages
   debug("Debug message")
   info("Info message")
   warning("Warning message")
   error("Error message")

**Advanced Configuration:**

.. code-block:: python

   from zefir.logging import configure_log, LogLevel
   import pathlib

   # Log to file and stream
   configure_log(
       level=LogLevel.INFO,
       file=pathlib.Path("zefir.log"),
       stream=True
   )

**GUI Integration:**

The GUI automatically connects to the logging system and displays messages in the log console panel.

Examples
--------

See the ``sandbox/`` directory for example scripts demonstrating various flow configurations.