update

Author: masoudzp

docs/FAQ.md

@@ -16,16 +16,16 @@ from thousands of beamlets).
 
 ### **Can I use other open-source software for dose calculation and PortPy for planning optimization?**
 One of PortPy’s goals is to generate **clinically usable, deliverable plans** with dose calculations  
-that match commercial TPS accuracy. Therefore, we currently do **not** support integrating  
-other open-source dose engines into PortPy.
-
-However, users are welcome to use other software for dose calculation and PortPy solely for  
-optimization **if clinical-level dose accuracy is not required** for their use case.
+that match commercial TPS accuracy. This focus makes PortPy not only a clinically relevant platform but also a 
+powerful research tool for benchmarking optimization algorithms and their resultant treatment plans against the 
+clinical plans. Therefore, we currently do **not** support integrating other open-source dose engines into PortPy. 
+However, users are welcome to use PortPy solely for planning optimization and perform dose calculations using other 
+software, provided this setup meets the needs of their research or application.
 
 ---
 
 ### **Can I do proton therapy optimization with PortPy?**
-Currently, PortPy only supports **photon therapy optimization**.  
+PortPy currently only supports **photon planning optimization**.  
 Proton therapy support is expected to be released in 2026.
 
 ---

docs/contact_us.md

@@ -6,5 +6,5 @@ If you prefer to communicate via email:
 - For technical questions, contact the lead developer:  
    Gourav Jhanwar — [jhanwarg@mskcc.org](mailto:jhanwarg@mskcc.org)
 
-- For general inquiries, contact the PI:  
+- For general inquiries (e.g., colaboration, tutorial for your group, licensing), contact the PI:  
    Masoud Zarepisheh — [zarepism@mskcc.org](mailto:zarepism@mskcc.org)

docs/images/Linac_infMatrix.png

@@ -1,22 +1,65 @@
 # **What is PortPy?**
 
-<img src="./images/Linac.gif" align="right" alt="Radiotherapy 101" width="30%" height="30%" margin-right="10px">
+<img src="./images/Linac.gif" align="right" alt="Radiotherapy 101" width="40%" height="40%" margin-right="10px">
 
 **PortPy**, short for **P**lanning and **O**ptimization for **R**adiation **T**herapy, is an open-source Python library 
 designed to advance cancer radiotherapy treatment planning optimization. Radiotherapy plays a critical role in 
 treating over half of all cancer patients, whether as a standalone treatment or in combination with surgery, 
 chemotherapy, or immunotherapy. It works by delivering high-energy radiation beams to tumors, aiming to destroy 
 cancerous cells while minimizing damage to the surrounding healthy tissues. 
-Given that each patient has a unique anatomy, it is essential to customize the 
-radiation beams' shape, angle, and intensity. The goal is to maximize damage to the 
-tumor while minimizing exposure to healthy surrounding tissues. This challenge translates into modeling and 
-solving large-scale, 
-patient-specific mathematical optimization problems. PortPy aims to accelerate research 
-in this interdisciplinary field by offering **tools**, **baseline algorithms**, and **benhcmark datasets**.
+Since every patient has a unique anatomy, the radiation beam’s shape, angle, and intensity must be carefully 
+customized. The objective is to maximize tumor dose while minimizing exposure to nearby organs at risk—a 
+challenge that translates into solving large-scale, patient-specific mathematical optimization problems.
 
+PortPy aims to accelerate research in this interdisciplinary field by providing tools and algorithms 
+to model and solve these complex optimization problems, as well as to visualize and quantitatively 
+evaluate the resulting treatment plans (see image below).
 
 
-## 🚀 Main Features
+<img src="./images/Visualization.png" align="center" width="100%" height="70%">
+
+[//]: # ()
+[//]: # (# 👀 What is Radiotherapy Treatment Planning Optimization?)
+
+[//]: # (<img src="./images/Linac_infMatrix.png" align="center" width="100%" height="70%">)
+
+[//]: # ()
+[//]: # (In radiotherapy, the patient lies on a couch while a )
+
+[//]: # (linear accelerator rotates around them to deliver radiation &#40;Figure a&#41;. The radiation beams are shaped using )
+
+[//]: # (a set of metal leaves known as a multi-leaf collimator &#40;MLC&#41;, which dynamically move in-and-out to modulate )
+
+[//]: # (the beam shape. This allows radiation to be precisely targeted at the tumor from multiple directions, )
+
+[//]: # (effectively placing it in the crossfire &#40;Figure b&#41;. Optimizing the angle, shape, and intensity of these )
+
+[//]: # (beams for each individual patient, can be formulated as a mathematical optimization problem. )
+
+[//]: # (For this, the patient's anatomy is discretized into 3D voxels and each beam is subdivided into 2D beamlets and )
+
+[//]: # (the radiation dose contribution from each beamlet to each )
+
+[//]: # (voxel is precomputed &#40;Figure c&#41;, and stored in a matrix commonly referred to as the dose influence matrix )
+
+[//]: # (&#40;or dose deposition matrix&#41;. )
+
+[//]: # ()
+[//]: # (PortPy provides tools to model and solve these optimization problems that are often large-scale and non-convex.)
+
+[//]: # (PortPy also provides a set of tools for visual and quantitative assessment of treatment plans, including: dose distribution &#40;Figure e&#41;)
+
+[//]: # (beamlet intensity maps for individual beams &#40;Figure e&#41;, dose-volume histograms &#40;DVHs, Figure f&#41;, and a color-coded table that)
+
+[//]: # (compares quantitative dose metrics against clinical criteria &#40;Figure g&#41;.)
+
+[//]: # ()
+[//]: # (<img src="./images/Visualization.png" align="center" width="90%" height="60%">)
+
+[//]: # ()
+
+
+## 🚀 PortPy Main Features
 
 - **IMRT/VMAT Planning Optimization (including AI):**  
   Includes support for IMRT fluence map optimization and leaf sequencing (see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/1_basic_tutorial.ipynb)), 
@@ -52,89 +95,5 @@ system, **ECHO**, are included for benchmarking
       (i.e., good but not neceassirily optimal) solution quickly for the current VMAT SCP (Sequential Convex Programming) optimization algorithm (see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_scp_tutorial.ipynb)).
      - **Enhanced visualization**: The evaluation table has been improved for better readability and analysis (see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/1_basic_tutorial.ipynb)). 
 
-[//]: # ()
-[//]: # (## 🚀 Key Components: Benchmark Datasets, Baseline Algorithms, and PortPy Toolkit)
-
-[//]: # ()
-[//]: # (<img src="./images/AI_Pyramid.png" align="right" alt="Radiotherapy 101" width="50%" height="40%">)
-
-[//]: # (  )
-[//]: # (This pyramid figure illustrates the inspiration behind developing PortPy, drawing from )
-
-[//]: # (successful open-source practices in the AI and computer science communities. )
-
-[//]: # (Tools like PyTorch and TensorFlow, along with benchmark datasets such as )
-
-[//]: # (ImageNet and algorithms like AlexNet, have revolutionized AI and data science. )
-
-[//]: # (Our goal is to replicate this successful model in the field of radiotherapy by )
-
-[//]: # (equipping researchers with PortPy toolkit, benchmark algorithms, and datasets, )
-
-[//]: # (as outlined below:)
-
-[//]: # ()
-[//]: # (1. **PortPy Toolkit**. A set of python classes and functions allowing users to load the data, )
-
-[//]: # (generate IMRT/VMAT plans, and evaluate/visualize the results. For more info, see our Jupyter Notebooks [basic_tutorial]&#40;&#41;)
-
-[//]: # (2. **Benchmark Datasets**. We have curated and made publicly available a dataset of 100 lung cancer patients,)
-
-[//]: # (which includes all the necessary data for treatment plan optimization &#40;e.g., beamlets, voxels, pre-computed dose influence matrix&#41;. )
-
-[//]: # (These data are extracted from the commercial Eclipse treatment planning system using its API. Using your own data is currently only supported for Eclipse TPS users. For more info, see our Jupyter Notebooks &#40;[eclipse_photon_dose_calculation]&#40;https://github.com/PortPy-Project/PortPy/blob/master/examples/eclipse_photon_dose_calculation.ipynb&#41;)
-
-[//]: # (3. **Baseline Algorithms**. This includes two sets of algorithms: 1&#41; fast algorithms that can generate IMRT/VMAT plans within the clinical time-frame &#40;in oder of minutes/hours&#41;,)
-
-[//]: # (2&#41; slow algorithms that can generate globally optimal plans for benchmaking purposes. These plans could take weeks to generate and often involve some simplistic assumptions &#40;e.g., ignoring plan delivery efficiency in VMAT&#41;.)
-
-[//]: # ()
-[//]: # (> Modern Portfolio Optimization in Python)
-
-[//]: # ()
-[//]: # (---)
-
-[//]: # (Test7)
-
-[//]: # (Welcome to **PortPy**! Effortlessly optimize, analyze, and visualize your investment portfolios with a modern, user-friendly Python library.)
-
-[//]: # ()
-[//]: # (<div align="center">)
-
-[//]: # (  <img src="https://raw.githubusercontent.com/your-org/portpy/main/assets/logo.png" alt="PortPy Logo" width="180"/>)
-
-[//]: # (</div>)
-
-[//]: # ()
-[//]: # (---)
-
-[//]: # ()
-[//]: # ()
-[//]: # ()
-[//]: # (---)
-
-[//]: # ()
-[//]: # (## Get Started)
-
-[//]: # ()
-[//]: # (- [Installation Guide]&#40;installation.md&#41;)
-
-[//]: # (- [Quickstart Tutorial]&#40;quickstart.md&#41;)
-
-[//]: # (- [API Reference]&#40;reference/&#41;)
-
-[//]: # (- [GitHub Repository]&#40;https://github.com/your-org/portpy&#41;)
-
-[//]: # ()
-[//]: # (---)
-
-[//]: # ()
-[//]: # (---)
-
-[//]: # ()
-[//]: # (<div align="center">)
-
-[//]: # (  <a href="quickstart.md"><b>Start Optimizing Your Portfolio →</b></a>)
 
-[//]: # (</div>)
 

docs/images/Visualization.png

@@ -1,48 +1,35 @@
 ## Installation
-1. **Using pip**:
-   
-    * Run the command
-      ```
-      pip install portpy
-      ```
-    * You can install optional packages using
-      ```
-      pip install portpy[mosek, pydicom]
-      ```
-   * For installing AI related packages
-     ```
-      pip install portpy[ai]   
-     ```
-   * For installing all the additional packages
-     ```
-      pip install portpy[all]   
-     ```
+???+ example "Installing PortPy"
 
-2. **From source**:
-   
-    * Clone this repository using
-      ```
-      git clone https://github.com/PortPy-Project/PortPy.git
-      ```
-    * Navigate to the repository with
-      ```
-      cd portpy
-      ```
+    === "pip/conda"
 
-    * Install the dependencies within a Python virtual environment or Anaconda environment. To set up in a Python virtual environment, install all the dependencies specified in requirements.txt as follows:
-        * Create the virtual environment with
-          ```
-          python3 -m venv venv
-          ```
-        * Activate the environment with 
-          ```
-          source venv/bin/activate
-          ```
-        * Install the requirements using
-          ```
-          pip install -r requirements.txt
-          ```
+        To install PortPy with all its dependecies (recommonded).
+        ```bash
+        pip install portpy[all]
+        ```
+        To install PortPy with only optional dependencies.
+        ```bash
+        pip install portpy[ai, mosek, pydicom]
+        ```
+        To install PortPy with only the core dependencies.
+        ```bash
+        pip install portpy
+        ```
 
+    === "From source"
+
+        1- Clone this repository 
+        ```bash
+        git clone https://github.com/PortPy-Project/PortPy.git
+        ```
+        2- Navigate to the repository 
+        ```bash
+        cd portpy
+        ``` 
+        3- Install the dependencies within a Python/Anaconda virtual environment 
+              ```bash
+              pip install -r requirements.txt
+              ```        
 
 ## Quick Start Guide
 

docs/index.md

@@ -28,4 +28,37 @@
     transition: width 0.3s ease !important;  Optional: smooth transition */
 
   }
-  
+/* Base table style */
+.md-typeset table {
+  font-size: 16px;
+  border-collapse: collapse;
+}
+
+.md-typeset table td,
+.md-typeset table th {
+  padding: 12px 16px;
+}
+
+/* First column background + custom link color */
+.md-typeset table tr td:first-child,
+.md-typeset table tr th:first-child {
+  background-color: #f5f5f5; /* Light blue */
+}
+
+/* Second column background */
+.md-typeset table tr td:nth-child(2),
+.md-typeset table tr th:nth-child(2) {
+  background-color: #fffbea; /* Light yellow */
+}
+
+/* Custom hyperlink color in first column */
+.md-typeset table tr td:first-child a {
+  color: #1a5e9a;           /* A deep, professional blue */
+  text-decoration: none;    /* Remove underline */
+  font-weight: 500;         /* Slightly bold for visibility */
+}
+
+.md-typeset table tr td:first-child a:hover {
+  color: #104d80;           /* Darker on hover */
+  text-decoration: underline;
+}

docs/quick_start.md

@@ -102,7 +102,11 @@ markdown_extensions:                                    # Adds features to Markd
   - pymdownx.superfences                                # Enables nested code blocks
   - pymdownx.highlight                                  # Syntax highlighting for code blocks
   - pymdownx.details                                    # Expandable details blocks
-  - pymdownx.tabbed                                     # Tabbed content blocks
+  - pymdownx.tabbed:                                     # Tabbed content blocks
+     alternate_style: true
+  - pymdownx.arithmatex:
+     inline_syntax: ['dollar']
+
 
 # -------- Extra Site Settings --------
 
@@ -112,9 +116,13 @@ extra:
       link: https://github.com/PortPy-Project/PortPy
     - icon: fontawesome/brands/python
       link: https://pypi.org/project/portpy-photon/
+  arithmatex:
+    inline: '$'
+    block: '$$'
 
 extra_javascript: # Include custom JavaScript files
   - js/extra.js
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
 
 extra_css: # Include custom CSS files
   - styles/extra.css