Usage Guide#

Command-Line Interface (CLI)#

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

Basic Usage:

# 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:

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:

# 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

from zefir.gui.potential import main
main()

Method 2: Creating the GUI manually

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

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:

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:

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:

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.