Metadata-Version: 2.4
Name: q1ram
Version: 0.1.5
Summary: Q1RAM Python client for interacting with the Quantum RAM API
Home-page: https://github.com/yourusername/q1ram-client
Author: Ahmed Eisa
Author-email: ahmed.m.easa@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: python-dotenv
Requires-Dist: qiskit>=2.0.0
Requires-Dist: requests
Requires-Dist: qiskit_qasm3_import
Requires-Dist: pylatexenc
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Q1RAM Client API Methods

This document explains the main methods provided by the Q1RAM client API for quantum random access memory operations. These methods allow you to manipulate quantum memory in both single and superposition states.

## 1. `read`

**Purpose:**  
Reads data from the Q1RAM at a specified address or in superposition.

**Signature:**  
```python
read(address_register=None, data_register=None, address_value=None, data_value=None)
```

**Parameters:**
- `address_register`: Optional. QuantumRegister or list specifying the address qubits.
- `data_register`: Optional. QuantumRegister or list specifying the data qubits.
- `address_value`: Optional. List of integers specifying the classical address to read from. If omitted, reads in superposition.
- `data_value`: Optional. List of integers specifying the classical data to match (rarely used for read).

**Usage Examples:**
- Read from a superposition address states:
  ```python
  qram.read(address_value=[0, 1])
  ```

---

## 2. `write`

**Purpose:**  
Writes data to the Q1RAM at a single or superposition address states.

**Signature:**  
```python
write(address_register=None, data_register=None, address_value=None, data_value=None)
```

**Parameters:**
- `address_register`: Optional. QuantumRegister or list specifying the address qubits.
- `data_register`: Optional. QuantumRegister or list specifying the data qubits.
- `address_value`: Optional. List of integers specifying the classical address to write to. If omitted, writes in superposition.
- `data_value`: Required. List of integers specifying the data to write.

**Usage Examples:**
- Write to a specific address:
  ```python
  qram.write(address_value=[0, 1], data_value=[5])
  ```

---

## 3. `read_all` 

**Purpose:**  
Reads all data from Q1RAM, typically used to retrieve the full memory contents.

**Signature:**  
```python
read_all()
```

**Usage Example:**
```python
qram.read_all()
```

---


## Authentication

Before using any method, authenticate with the API:
```python
from q1ram import authenticate
authenticate()
```

---

## Example Workflow

```python
from q1ram_client.q1ram.circuit import Q1RAM, authenticate
from qiskit import QuantumCircuit

authenticate()
qc = QuantumCircuit()
qram = Q1RAM(qc, number_address_qubits=2, number_data_qubits=2)

# Write data to address [0, 1]
qram.write(address_value=[0, 1], data_value=[1, 0])

# Read data from address [0, 1]
qram.read(address_value=[0, 1])

# Write data in superposition
qram.write(data_value=[1, 1])

# Read all data in superposition
qram.read()
```

---

## Notes

- All API calls require valid authentication credentials, by registering on [https://q1ram.com](https://q1ram.com).
- The methods interact with the Q1RAM backend via HTTP requests and update the local quantum circuit accordingly.
- For advanced usage, you can provide custom quantum registers for address and data.
