Skip to content

Project Structure

Jump to bottom
Mohammadreza Khellat edited this page Dec 16, 2025 · 1 revision

Project Structure

Understanding the organization and structure of the openqcp-lab repository.

Table of Contents

  1. Directory Layout
  2. File Organization
  3. Naming Conventions
  4. Finding Content
  5. Repository Navigation

Directory Layout

Root Directory

openqcp-lab/
├── 6.B/                          # Academic papers and resources
├── coupled_harmonic_oscillators/  # Tutorial 05
├── minimize_expectation_value/    # Tutorial 01
├── nonunitary_quantum_computing/  # Tutorial 03
├── quantum_fourier_transform_abelian/  # Tutorial 00
├── quantum_variational_algorithms/     # Tutorial 04
├── quantum_walk/                 # Tutorial 02
├── CONTRIBUTING.md               # Contribution guidelines
├── LICENSE                       # GNU GPL v3+ license
├── Makefile                      # Build automation
├── NOTEBOOK_TEMPLATE.md          # Notebook structure template
├── README.md                     # Main project documentation
├── REPRODUCING_RESULTS.md        # Results reproduction guide
├── requirements.txt              # Python dependencies
└── setup_env.sh                  # Environment setup script

Tutorial Directories

Each tutorial has its own directory:

tutorial_name/
├── README.md              # Tutorial-specific documentation
├── *.ipynb                # Jupyter notebooks
├── *.qmod                 # Quantum model files (generated)
├── *.qprog                # Quantum program files (generated)
└── figures/               # Generated figures (if applicable)

File Organization

Documentation Files

Root Level:

  • README.md - Main project documentation, setup instructions
  • CONTRIBUTING.md - How to contribute to the project
  • REPRODUCING_RESULTS.md - How to reproduce results
  • NOTEBOOK_TEMPLATE.md - Template for new notebooks

Tutorial Level:

  • Each tutorial directory contains a README.md with:
    • Theory and implementation details
    • Software requirements
    • Expected outputs
    • Contributor information

Code Files

Notebooks:

  • *.ipynb - Jupyter notebook files
  • Located in respective tutorial directories
  • Contain executable code and documentation

Python Scripts:

  • *.py - Standalone Python scripts (if any)
  • Located in tutorial directories or 6.B/advanced design/

Generated Files

Quantum Models:

  • *.qmod - Quantum model files (Classiq)
  • *.qprog - Quantum program files (Classiq)
  • Generated when notebooks are executed
  • Optional - not required for notebooks to run

Figures:

  • *.png - Generated plots and figures
  • Located in figures/ subdirectories
  • Some are precomputed examples

Data Files:

  • *.csv - Measurement results (if any)
  • Located in tutorial directories

Academic Resources

Papers:

  • 6.B/*.pdf - Academic papers in PDF format
  • Organized by author and year
  • Related to tutorial topics

Advanced Examples:

  • 6.B/advanced design/*.py - Advanced Python examples
  • 6.B/quantum primitives */ - Quantum primitive examples

Naming Conventions

Tutorial Directories

Tutorial directories use descriptive names:

  • quantum_fourier_transform_abelian/ - Descriptive, lowercase, underscores
  • minimize_expectation_value/ - Clear purpose
  • quantum_walk/ - Concise, descriptive

Notebook Files

Notebook files use descriptive names:

  • qft_abelian_qpe_hadamard.ipynb - Descriptive of content
  • minimize_vqc_output.ipynb - Clear purpose
  • N_coupled_harmonic_oscillators_1_D_N_2.ipynb - Includes parameters

Generated Files

Generated files follow patterns:

  • *.qmod - Quantum model files
  • N-2-dt-*.qmod - Includes parameters in filename
  • figures/hs_n_2.png - Descriptive figure names

Finding Content

By Tutorial Number

# Tutorial Directory
00 Quantum Fourier Transform quantum_fourier_transform_abelian/
01 Minimize Expectation Value minimize_expectation_value/
02 Quantum Walk quantum_walk/
03 Non-Unitary Computing nonunitary_quantum_computing/
04 Quantum Variational Algorithms quantum_variational_algorithms/
05 Coupled Harmonic Oscillators coupled_harmonic_oscillators/

By Framework

Classiq Tutorials:

  • Tutorial 00: quantum_fourier_transform_abelian/
  • Tutorial 02: quantum_walk/
  • Tutorial 03: nonunitary_quantum_computing/
  • Tutorial 05: coupled_harmonic_oscillators/

PennyLane Tutorials:

  • Tutorial 01: minimize_expectation_value/

Qiskit Tutorials:

  • Tutorial 04: quantum_variational_algorithms/

By Topic

Optimization:

  • Tutorial 01: minimize_expectation_value/
  • Tutorial 04: quantum_variational_algorithms/

Simulation:

  • Tutorial 05: coupled_harmonic_oscillators/

Algorithms:

  • Tutorial 00: quantum_fourier_transform_abelian/
  • Tutorial 02: quantum_walk/
  • Tutorial 03: nonunitary_quantum_computing/

By Difficulty

Beginner:

  • Tutorial 00: quantum_fourier_transform_abelian/
  • Tutorial 01: minimize_expectation_value/

Intermediate:

  • Tutorial 02: quantum_walk/
  • Tutorial 03: nonunitary_quantum_computing/
  • Tutorial 04: quantum_variational_algorithms/

Advanced:

  • Tutorial 05: coupled_harmonic_oscillators/

Repository Navigation

Quick Start

  1. Clone Repository:

    git clone https://codeberg.org/mkhellat/openqcp-lab.git
cd openqcp-lab

  2. Read Main README:

    • Start with README.md for overview and setup

  3. Choose Tutorial:

  4. Read Tutorial README:

    • Each tutorial has its own README.md

  5. Open Notebook:

    • Open .ipynb file in Jupyter

Finding Specific Files

Setup Files:

  • setup_env.sh - Environment setup
  • requirements.txt - Dependencies
  • Makefile - Build automation

Documentation:

  • README.md - Main documentation
  • CONTRIBUTING.md - Contribution guide
  • Tutorial README.md files

Academic Resources:

  • 6.B/*.pdf - Papers
  • 6.B/advanced design/ - Advanced examples

Generated Content:

  • *.qmod, *.qprog - Quantum models (generated)
  • figures/*.png - Figures (some precomputed)

File Types and Extensions

Documentation

  • .md - Markdown documentation files
  • .pdf - PDF papers and documents

Code

  • .ipynb - Jupyter notebooks
  • .py - Python scripts
  • .qmod - Quantum model files (Classiq)
  • .qprog - Quantum program files (Classiq)

Data

  • .csv - Comma-separated values (measurement results)
  • .json - JSON configuration files

Images

  • .png - Plot and figure images

Understanding the Structure

Tutorial Organization

Each tutorial is self-contained:

  • README.md - Documentation
  • Notebook(s) - Executable code
  • Optional files - Generated models, figures, data

Academic Resources

The 6.B/ directory contains:

  • Papers - PDF files organized by author/year
  • Advanced examples - Additional code examples
  • Quantum primitives - Example quantum operations

Configuration Files

Root-level configuration:

  • requirements.txt - Python dependencies
  • Makefile - Build and automation targets
  • setup_env.sh - Environment setup script

Best Practices

When Adding Content

  1. Follow Naming Conventions:

    • Use lowercase with underscores
    • Be descriptive
    • Include parameters in filenames if relevant

  2. Organize by Tutorial:

    • Keep tutorial files in tutorial directories
    • Use subdirectories for figures/data if needed

  3. Document Everything:

    • Update README files
    • Add comments in code
    • Document generated files

  4. Version Control:

    • Don't commit generated files unnecessarily
    • Keep repository clean
    • Use .gitignore appropriately

Additional Resources

Return to: Home | Tutorial Catalog | Getting Started

Clone this wiki locally