Update readme

CHANGELOG.md

@@ -20,6 +20,7 @@ Types of changes:
 
 ### Improved / Modified
 - Added `slots=True` parameter to the data classes in `elements.py` to improve memory efficiency ([#218](https://github.com/qBraid/pyqasm/pull/218))
+- Updated the documentation to include core features in the `README` ([#219](https://github.com/qBraid/pyqasm/pull/219))
 
 ### Deprecated
 

README.md

@@ -15,7 +15,7 @@ Python toolkit providing an OpenQASM 3 semantic analyzer and utilities for progr
 [![Env Badge](https://img.shields.io/endpoint?url=https://api.qbraid.com/api/environments/valid?envSlug=pyqasm_l9qauu&label=Launch+on+qBraid&labelColor=lightgrey&logo=rocket&logoSize=auto&style=for-the-badge)](http://account.qbraid.com?gitHubUrl=https://github.com/qBraid/pyqasm.git&envId=pyqasm_l9qauu)
 
 ## Motivation
-[OpenQASM](https://openqasm.com/) is a powerful language for expressing hybrid quantum-classical programs, but it lacks a comprehensive tool supporting the full capabilities of the language. PyQASM aims to fill this gap by building upon the [`openqasm3.parser`](https://github.com/openqasm/openqasm/blob/ast-py/v1.0.1/source/openqasm/openqasm3/parser.py), and providing support for semantic analysis and utilities for program compilation.
+[OpenQASM](https://openqasm.com/) is a powerful language for expressing hybrid quantum-classical programs, but it lacks a comprehensive tool supporting the _full capabilities of the language_. PyQASM aims to fill this gap by building upon the [`openqasm3.parser`](https://github.com/openqasm/openqasm/blob/ast-py/v1.0.1/source/openqasm/openqasm3/parser.py), and providing support for semantic analysis and utilities for program compilation.
 
 ## Installation
 
@@ -26,24 +26,21 @@ pip install pyqasm
 ```
 
 ### Optional Dependencies
+PyQASM offers optional extras such as - 
+1. `cli` : command-line interface (CLI) functionality
+2. `visualization`: for program visualization 
+3. `pulse` : pulse/calibration features (in progress)
 
-PyQASM provides an optional extra called pyqasm[pulse] that adds pulse/calibration features.
-
+To install these features along with the core package, you can use the following command:
 ```bash
-pip install pyqasm[pulse]
+pip install 'pyqasm[cli,pulse,visualization]'
 ```
 
-PyQASM also offers optional extras for command-line interface (CLI) functionality and for program visualization.
-
-To install the CLI tools:
+You can also install them individually. For example, to install the CLI features only, you can run:
 ```bash
-pip install pyqasm[cli]
+pip install 'pyqasm[cli]'      
 ```
 
-To install the visualization tools:
-```bash
-pip install pyqasm[visualization]
-```
 
 ### Install from source 
 
@@ -65,6 +62,89 @@ You can view the version of pyqasm you have installed within a Python shell as f
 >>> pyqasm.__version__
 ```
 
+## Key Features: Unroll & Validate OpenQASM 3 Programs
+
+PyQASM offers robust support for the **extensive grammar of OpenQASM 3**, including custom gates, subroutines, loops, conditionals, classical control, and more. Its core utilities allow you to **validate** programs for semantic correctness and **unroll** (flatten) all high-level constructs into a linear sequence of basic quantum operations, ready for execution or further compilation.
+
+### Highlights
+
+- **[Comprehensive Grammar Support](src/README.md)**: PyQASM supports the full breadth of OpenQASM 3 operations, and backward compatibility with OpenQASM 2, including:
+  - Classical and quantum registers
+  - Loops (`for`, `while`)
+  - Conditionals (`if`, `else`)
+  - Parameterized and custom gates
+  - Subroutine inlining
+  - Switch statements
+  - Classical expressions and assignments
+  - Variables and arrays
+  - Type casting and conversions
+  - Built-in and user-defined constants
+  - Quantum-classical interaction (`measurement`, `reset`, etc.)
+  - Inclusion of standard libraries (`stdgates.inc`, etc.)
+
+- **[Unrolling](https://docs.qbraid.com/pyqasm/user-guide/examples#inlining-%26-unrolling):**  
+  Expands all custom gates, loops, subroutines, branches, etc. into a flat, hardware-ready sequence of instructions.
+
+- **[Validation](https://docs.qbraid.com/pyqasm/user-guide/overview#the-qasmmodule-object):**  
+  Performs semantic analysis to ensure programs are correct and conform to the OpenQASM 3 specification.
+
+---
+
+### Example: Unroll and Validate a Complex QASM Program
+
+Below is an example demonstrating PyQASM's efficacy on a non-trivial OpenQASM 3 program. This program uses custom gates, loops, and classical control, and is fully unrolled and validated by PyQASM:
+
+```python
+from pyqasm import loads, dumps
+
+qasm = """
+OPENQASM 3;
+include "stdgates.inc";
+
+gate h2 a, b { h a; h b; }
+def parity_flip(qubit[4] q) {
+    for int i in [0:3] {
+        if (i % 2 == 0) {
+            x q[i];
+        }
+    }
+}
+
+qubit[4] q;
+bit[4] c;
+
+h2 q[0], q[1];
+parity_flip(q);
+
+for int i in [0:3] {
+    measure q[i] -> c[i];
+}
+"""
+
+module = loads(qasm)      # Parse and build the program
+module.validate()         # Check for semantic errors
+module.unroll()           # Flatten all gates, loops, and subroutines
+
+print(dumps(module))      # Output the fully unrolled QASM
+```
+
+**Output (fully unrolled QASM):**
+```qasm
+OPENQASM 3.0;
+include "stdgates.inc";
+qubit[4] q;
+bit[4] c;
+h q[0];
+h q[1];
+x q[0];
+x q[2];
+c[0] = measure q[0];
+c[1] = measure q[1];
+c[2] = measure q[2];
+c[3] = measure q[3];
+```
+
+PyQASM ensures your OpenQASM programs are **semantically correct** and **hardware-ready**, supporting the language's most advanced features with ease.
 ## Resources
 
 - [API Reference](https://qbraid.github.io/pyqasm/api/pyqasm.html): Developer documentation.

src/README.md

@@ -27,8 +27,8 @@ Source code for OpenQASM 3 program validator and semantic analyzer
 | RangeDefinition                | ✅          | Completed              |
 | QuantumGate                    | ✅          | Completed              |
 | Cast                           | ✅          | Completed              |
-| QuantumGateModifier (ctrl)     | 📋          | Planned                |
-| WhileLoop                      | 📋          | Planned                |
+| QuantumGateModifier (ctrl)     | ✅          | Completed              |
+| WhileLoop                      | ✅          | Completed              |
 | IODeclaration                  | 📋          | Planned                |
 | Pragma                         | 📋          | Planned                |
 | Annotation                     | 📋          | Planned                |