Overhaul Q50 model (#28)

* Update documentation

* Update documentation

* Update resource estimator defaults for values and remove depth from q50 entry

* Update cli tool

* Add method to train simple linear model, improve docstrings

* Add Helmi model type, add new analytical model for Q50

* Update and add new tests

* Update changelog

* Update actual vs predicted plot

* Update documentation

* Update creation of plots

* Clean up codebase and move logic to new modules

Author: JMuff22

CHANGELOG.rst

@@ -2,11 +2,14 @@
 Changelog
 =========
 
-Version 0.3.1
+Version 0.4.0
 ==========================
 
-* Add device-specific qubit limits
-* Display maximum qubit count hint in the UI for each device
+* Overhauled VTT Q50 model to use an analytical model without a depth parameters
+  * Not using depth avoids numerical instability and unphysical behavior while maintaining high accuracy
+* Updated UI to remove depth input and reflect new model structure
+* Modify the CLI build process to allow both Helmi (polynomial model) and Q50 (analytical model) approaches
+* Update the documentation.
 
 Version 0.3.0
 ============

public/actual_vs_predicted-vtt-q50.png

@@ -3,9 +3,9 @@
 
 Data is gathered by submitting quantum circuits with varying values for shots, depth, number of circuits in a batch and number of qubits. You can view the data gathered [here](https://github.com/FiQCI/resource-estimator/tree/main/data_analysis/data). QPU seconds is calculated from timestamps returned via IQM Client as explained [here](https://docs.meetiqm.com/iqm-client/integration_guide.html#job-phases-and-related-timestamps). QPU seconds is calculated as `execution_end` - `execution_start`.
 
-The data is analyzed using **polynomial ridge regression models** implemented with scikit-learn's [`Ridge`](https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.Ridge.html) and [`PolynomialFeatures`](https://scikit-learn.org/stable/modules/generated/sklearn.preprocessing.PolynomialFeatures.html). A separate model is created for each quantum computer:
-- **Helmi**: Degree-2 polynomial
-- **VTT Q50**: Degree-3 polynomial with **log-transform**
+The data is analyzed using different modeling approaches depending on the quantum computer:
+- **Helmi**: Polynomial ridge regression model (degree-2) implemented with scikit-learn's [`Ridge`](https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.Ridge.html) and [`PolynomialFeatures`](https://scikit-learn.org/stable/modules/generated/sklearn.preprocessing.PolynomialFeatures.html)
+- **VTT Q50**: Analytical model.
 
 ## Helmi
 
@@ -21,15 +21,19 @@ Where $kshots = shots/1000$ and $B$ is number of circuits in a batch.
 
 ## VTT Q50
 
-The model for VTT Q50 uses a **degree-3 polynomial regression with log-transform**. The equation (showing only the most significant terms) is:
+The model for VTT Q50 uses an **analytical model** that tries to capture the scaling of parameters:
 
-$$\log(QPU + 0.001) = -0.531 + 0.364 \times B + 0.221 \times kshots + 0.030 \times qubits - 0.022 \times B^2 + ...$$
+$$T = T_{init} + \eta(B) \times B \times shots \times \alpha$$
 
-$$QPU = \exp(\text{result}) - 0.001$$
+Where:
+- $T_{init} = ~0.88$ seconds (baseline overhead)
+- $\eta(B) = ~0.986^{\min(B, 19)}$ (batching efficiency factor)
+- $\alpha = ~0.000625$ (throughput coefficient)
+- $B$ = number of circuits in a batch
 
-Where only the most significant terms are included. This shows that VTT Q50 is strongly dependent on batches and shots. VTT Q50 has a baseline initialization time of approximately **1.2 seconds**.
+Note that the circuit depth does not affect runtime by a noticeable amount. The number of qubits has a minimal impact.
 
-Where $kshots = shots/1000$ and $B$ is number of circuits in a batch.
+The initialization overhead ($T_{init}$) is approximately **1.1-1.2 seconds**.
 
 ![image](./actual_vs_predicted-vtt-q50.png)
 
@@ -43,6 +47,10 @@ The model does not work well for circuits with a high depth (`>1000`) count, how
 
 Both VTT Q50 and Helmi have a constant initialization time associated with any quantum job submitted to them. For a batch of circuits, the constant initialization time applies to the whole batch (list of circuits). However, submitting many smaller batches of quantum circuits does apply this time. This is mostly due to the initialization of the control electronics needed before job submission.
 
+- **Why does VTT Q50's model not include circuit depth or qubit count?**
+
+The circuit depth and number of qubits has minimal impact on QPU execution time. The runtime is largely dominated by the number of circuit executions (shots × batches) and qubit count. Removing depth from the VTT Q50 model simplifies the estimation model.
+
 - **Is the initialization time needed every time a parameter is updated in the quantum circuit?**
 
 When running variational algorithms you often perform parameter updates outside of the quantum job. Therefore, for each parameter update the constant initialization time is added to the total runtime.

public/documentation.md

@@ -7,7 +7,7 @@ import { DEVICE_PARAMS, calculateQPUSeconds } from '../utils/ResourceEstimatorMo
 
 const fontFamily = '-apple-system,BlinkMacSystemFont,"Roboto","Segoe UI","Helvetica Neue","Lucida Grande",Arial,sans-serif';
 
-const ParameterInput = ({ label, value, onChange, hint, error }) => {
+const ParameterInput = ({ label, value, onChange, hint, error, disabled = false }) => {
 	const inputContainerStyle = {
 		flex: '1 0 45%',
 		marginBottom: '0.75rem',
@@ -20,7 +20,7 @@ const ParameterInput = ({ label, value, onChange, hint, error }) => {
 		display: 'block',
 		fontSize: '1.1rem',
 		fontWeight: '500',
-		color: '#374151',
+		color: disabled ? '#9CA3AF' : '#374151',
 		marginBottom: '0.35rem',
 		fontFamily: fontFamily
 	};
@@ -46,13 +46,14 @@ const ParameterInput = ({ label, value, onChange, hint, error }) => {
 		display: 'block',
 		width: '100%',
 		padding: '0.5rem 0.7rem',
-		backgroundColor: 'white',
+		backgroundColor: disabled ? '#F3F4F6' : 'white',
 		border: error ? '2px solid #DC2626' : '1px solid #D1D5DB',
 		borderRadius: '0.35rem',
 		boxSizing: 'border-box',
-		color: '#000',
+		color: disabled ? '#9CA3AF' : '#000',
 		fontFamily: fontFamily,
 		fontSize: '1.1rem',
+		cursor: disabled ? 'not-allowed' : 'text',
 		// Hide up/down arrows for number inputs
 		WebkitAppearance: 'none',
 		MozAppearance: 'textfield'
@@ -81,6 +82,7 @@ const ParameterInput = ({ label, value, onChange, hint, error }) => {
 				onChange={handleInputChange}
 				style={inputStyle}
 				placeholder="Enter value"
+				disabled={disabled}
 			/>
 			{error ? <span style={errorStyle}>{error}</span> : hint && <span style={hintStyle}>{hint}</span>}
 		</div>
@@ -91,9 +93,9 @@ const ResourceEstimator = () => {
 	const [selectedDevice, setSelectedDevice] = useState('helmi');
 	const [formData, setFormData] = useState({
 		batches: 1,
-		depth: 10,
 		shots: 1000,
-		qubits: 5
+		qubits: 5,
+		depth: 1
 	});
 
 	const [estimatedQPU, setEstimatedQPU] = useState(null);
@@ -154,7 +156,10 @@ const ResourceEstimator = () => {
 
 	const calculateQPU = () => {
 		// Validate all fields first
-		const requiredFields = ['batches', 'depth', 'shots', 'qubits'];
+		const requiredFields = ['batches', 'shots', 'qubits'];
+		if (selectedDevice === 'helmi') {
+			requiredFields.push('depth');
+		}
 		requiredFields.forEach(field => validateField(field, formData[field]));
 
 		// Check if there are any validation errors
@@ -168,11 +173,15 @@ const ResourceEstimator = () => {
 		// Convert any string values to numbers
 		const numericFormData = {
 			batches: parseInt(formData.batches, 10),
-			depth: parseInt(formData.depth, 10),
 			shots: parseInt(formData.shots, 10),
 			qubits: parseInt(formData.qubits, 10)
 		}
 
+		// Add depth for Helmi
+		if (selectedDevice === 'helmi') {
+			numericFormData.depth = parseInt(formData.depth, 10);
+		}
+
 		// Calculate QPU seconds using our model
 		const qpuSeconds = calculateQPUSeconds(selectedDevice, numericFormData);
 		setEstimatedQPU(qpuSeconds);
@@ -313,27 +322,32 @@ const ResourceEstimator = () => {
 							label="Circuits in Batch"
 							value={formData.batches}
 							onChange={(value) => handleInputChange('batches', value)}
-						/>
-
-						<ParameterInput
-							label="Circuit Depth (Gates)"
-							value={formData.depth}
-							onChange={(value) => handleInputChange('depth', value)}
+							error={validationErrors.batches}
 						/>
 
 						<ParameterInput
 							label="Shots per Circuit"
 							value={formData.shots}
 							onChange={(value) => handleInputChange('shots', value)}
+							error={validationErrors.shots}
 						/>
 
 						<ParameterInput
 							label="Number of Qubits"
 							value={formData.qubits}
-						onChange={(value) => handleInputChange('qubits', value)}
-						hint={`Max: ${DEVICE_PARAMS[selectedDevice].max_qubits} qubits`}
-						error={validationErrors.qubits}
-					/>
+							onChange={(value) => handleInputChange('qubits', value)}
+							hint={`Max: ${DEVICE_PARAMS[selectedDevice].max_qubits} qubits`}
+							error={validationErrors.qubits}
+						/>
+
+						<ParameterInput
+							label="Circuit Depth"
+							value={formData.depth}
+							onChange={(value) => handleInputChange('depth', value)}
+							hint={selectedDevice === 'helmi' ? 'Number of layers in circuit' : 'Not used for VTT Q50'}
+							error={validationErrors.depth}
+							disabled={selectedDevice === 'vtt-q50'}
+						/>
 					</div>
 
 					<div style={{marginTop: '1rem', textAlign: 'center'}}>