Update README.md

README.md

@@ -10,5 +10,53 @@ pinned: false
 license: mit
 short_description: LLM for digital circuit timing
 ---
+# Digital Circuit Clock Frequency Calculator
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+A deterministic calculator that computes the maximum operating frequency for synchronous digital circuits based on timing constraints. This tool performs first-principles timing analysis and provides natural language explanations of the results.
+
+## Overview
+
+This application calculates the maximum clock frequency at which a synchronous digital circuit can reliably operate by analyzing setup and hold timing constraints. It helps digital designers understand timing closure and identify potential violations before fabrication.
+
+## Features
+
+- **Setup Time Analysis**: Calculates maximum frequency based on critical path timing
+- **Hold Time Verification**: Checks if hold constraints are satisfied at all clock frequencies
+- **Safety Margins**: Computes timing slack and safety factors for both constraints
+- **Natural Language Explanations**: Uses LLM to generate plain-English descriptions of results
+- **Interactive Interface**: Real-time calculations with immediate feedback
+- **Example Scenarios**: Pre-loaded cases covering FPGA, ASIC, and violation scenarios
+
+## Input Parameters
+
+All timing parameters are specified in **nanoseconds (ns)**:
+
+| Parameter | Symbol | Description | Typical Range |
+|-----------|--------|-------------|---------------|
+| Clock-to-Q Delay | T_cq | Time for flip-flop output to be valid after clock edge | 0.08 - 2.0 ns |
+| Max Logic Delay | T_logic | Longest combinational path between flip-flops (critical path) | 0.4 - 50 ns |
+| Min Logic Delay | T_logic_min | Shortest combinational path between flip-flops | 0.05 - 10 ns |
+| Setup Time | T_setup | Data must be stable before clock edge | 0.05 - 1.5 ns |
+| Hold Time | T_hold | Data must remain stable after clock edge | 0.01 - 0.8 ns |
+| Clock Skew | T_skew | Uncertainty in clock arrival times | 0.02 - 5.0 ns |
+
+## Output Results
+
+The calculator provides:
+
+1. **Maximum Operating Frequency**: Displayed in MHz or GHz
+2. **Minimum Clock Period**: Required clock period in nanoseconds
+3. **Setup Slack**: Timing margin for setup constraint (0 at F_max)
+4. **Hold Margin**: Timing margin for hold constraint (must be ≥ 0)
+5. **Hold Safety Factor**: Ratio of available to required hold time
+6. **Constraint Status**: Pass/fail verdict for both setup and hold
+7. **Recommendation**: Design guidance based on results
+8. **LLM Explanation**: Plain-English summary for non-experts
+
+## How to Use
+
+1. **Enter Timing Parameters**: Input the six timing values for your circuit design
+2. **Click "Calculate Maximum Frequency"**: Run the timing analysis
+3. **Review Results**: Check the numerical results table
+4. **Read Explanation**: Understand the natural language summary
+5. **Try Examples**: Click pre-loaded scenarios to see different cases