Usage Guide
Complete usage documentation for the QM NMR Calculator, covering the web interface and calculation concepts.
Target audience: Researchers running NMR calculations and interpreting results.
Prerequisites: Complete the Installation Guide before using this guide.
Introduction
The QM NMR Calculator provides quantum mechanical prediction of 1H and 13C NMR chemical shifts using density functional theory (DFT). You can interact with the calculator through:
- Web UI - Visual interface at
http://localhost:8000for molecule submission, job monitoring, and result visualization - REST API - Programmatic access for automation and integration (documented separately)
This guide covers:
- Web UI workflow (submit, status, results pages)
- DELTA50 single-conformer calculation workflow
- Solvent selection for COSMO solvation
- Calculation presets (B3LYP vs PBE0)
Web UI Workflow
The web interface consists of three main pages that guide you through the NMR calculation process.
Submit Page (/)
The home page is where you submit molecules for NMR calculation.
Molecule Input Options:
You can provide molecular structure in two ways (mutually exclusive):
SMILES String - Enter the SMILES representation of your molecule
- Example:
CCOfor ethanol,c1ccccc1for benzene - Live preview shows your molecule as you type (rendered by the depict API)
- The preview validates SMILES syntax before submission
- Example:
MOL/SDF File Upload - Upload a pre-built structure file
- Accepts
.moland.sdfformats - Single molecule per file
- Useful when you have 3D coordinates from other software
- Accepts
Required Settings:
| Setting | Description |
|---|---|
| Solvent | NMR solvent environment (see Solvent Selection) |
Optional Settings:
| Setting | Description |
|---|---|
| Preset | B3LYP (default) or PBE0; see Calculation Presets |
| Molecule Name | Label for your molecule (displayed in results) |
| Email Notification | Get notified when calculation completes |
Each job runs the DELTA50 single-conformer protocol: one RDKit 3D structure, DFT optimization, GIAO shielding, and DELTA50 linear scaling.
Submitting:
Click "Calculate NMR" to start the calculation. You'll be redirected to the status page to monitor progress.
Note: Invalid SMILES or unsupported file formats will show an error message. The molecule preview helps catch SMILES errors before submission.
Status Page (/status/{job_id})
After submission, you're redirected to the status page to monitor calculation progress.
Job Details Panel:
Shows your calculation settings:
- Job ID (unique identifier)
- Elapsed time since submission
- Input SMILES
- Solvent and preset selections
3D Molecule Preview:
An interactive 3D viewer shows the initial RDKit-generated geometry while the calculation runs. This is the starting structure before DFT optimization.
Step Progress Tracker:
Shows completion status for each calculation step:
- Geometry Optimization - DFT structure optimization
- NMR Calculation - Shielding tensor computation
- Post-processing - Spectrum generation and formatting
Auto-refresh Behavior:
The page automatically polls for updates every 3 seconds and redirects to the results page upon completion. If the job fails, an error message is displayed with the option to submit a new job.
Results Page (/results/{job_id})
The results page provides comprehensive visualization and download options for completed calculations.
Interactive 3D Viewer:
The main feature is a rotatable 3D molecular structure with chemical shift labels:
- Blue labels - 1H (proton) chemical shifts in ppm
- Orange labels - 13C (carbon) chemical shifts in ppm
- Click and drag to rotate, scroll to zoom
Spectrum Images:
- 1H NMR Spectrum - Simulated proton spectrum (click to enlarge)
- 13C NMR Spectrum - Simulated carbon spectrum (click to enlarge)
Both images can be downloaded as PNG files.
Chemical Shift Tables:
Separate tables for 1H and 13C shifts:
- Atom index (H1, H2... or C1, C2...)
- Chemical shift value in ppm
Downloads Section:
| Download | Description |
|---|---|
| Geometry (XYZ) | Optimized 3D coordinates in XYZ format |
| Geometry (SDF) | Optimized structure with connectivity in SDF format |
| Raw Output (ZIP) | Complete NWChem output files for detailed analysis |
| 1H Spectrum (PNG) | Simulated 1H NMR spectrum image |
| 13C Spectrum (PNG) | Simulated 13C NMR spectrum image |
| Structure (PNG) | 2D structure image |
Calculation Workflow (DELTA50)
Predictions follow the DELTA50 benchmark protocol: one conformer per molecule.
How it works:
- RDKit embeds an initial 3D structure (or you upload MOL/SDF coordinates)
- NWChem optimizes the geometry at 6-31G* (B3LYP in the gas phase, PBE0 with COSMO solvation)
- GIAO NMR shieldings are computed on the optimized structure at 6-311+G(2d,p) with COSMO solvation
- Shieldings are converted to ppm using DELTA50 linear scaling factors
Typical timing:
- B3LYP preset: roughly 15–45 minutes for small organic molecules (depends on size and CPU cores)
- PBE0 preset: similar wall time, with somewhat higher 13C accuracy in the benchmark
Limitations:
- Flexible molecules may have multiple low-energy conformations; a single geometry cannot reproduce experimental conformational averaging
- Match the DELTA50 assumptions when comparing to experimental spectra (same solvent, static structure)
Solvent Selection
Solvent environment affects both geometry optimization and NMR shielding calculations through the COSMO solvation model.
Available Solvents
| Solvent | Display Name | Common Use |
|---|---|---|
acetone | Acetone (Acetone-d6) | Medium polarity |
acetonitrile | Acetonitrile (CD3CN) | Polar aprotic |
benzene | Benzene (Benzene-d6) | Aromatic/nonpolar compounds |
chcl3 | Chloroform (CDCl3) | Standard organic chemistry |
dcm | Dichloromethane (CD2Cl2) | Halogenated solvent |
dmf | N,N-Dimethylformamide (DMF-d7) | High-boiling polar aprotic |
dmso | DMSO (DMSO-d6) | Polar compounds |
methanol | Methanol (Methanol-d4) | Protic polar solvent |
pyridine | Pyridine (Pyridine-d5) | Basic aromatic solvent |
thf | Tetrahydrofuran (THF-d8) | Ethereal solvent |
toluene | Toluene (Toluene-d8) | Aromatic nonpolar |
water | Water (D2O) | Aqueous samples |
COSMO Solvation Model
The calculator uses the Conductor-like Screening Model (COSMO) to simulate solvent effects:
What COSMO does:
- Creates a cavity around the solute molecule
- Models the solvent as a dielectric continuum
- Calculates electrostatic screening from induced surface charges
- Affects both molecular geometry and electronic properties
Impact on results:
- Polar groups experience different shielding in polar vs non-polar solvents
- Geometry can change slightly between solvents
- Hydrogen bonding effects are approximated (not explicit)
Choosing the Right Solvent
Match your experimental conditions:
The most important rule is to select the solvent that matches your experimental NMR spectrum. Solvent effects on chemical shifts can be significant (0.1-1.0 ppm for 1H).
Chloroform (CDCl3):
- Most common choice for organic molecules
- Good for non-polar to moderately polar compounds
- Use when your experimental spectrum was recorded in CDCl3
DMSO (DMSO-d6):
- Better for polar molecules with hydrogen bond donors/acceptors
- Common for pharmaceuticals, natural products
- Larger dielectric constant captures polar interactions
Gas phase (vacuum):
- Reference calculations without solvent effects
- Comparing with gas-phase experimental data
- Understanding intrinsic vs solvent-induced shifts
Note: If you don't know which solvent to use, CDCl3 is a safe default for most organic molecules.
Calculation Presets
A preset fixes the DFT functional and the protocol around it. There are two, named after their functional: B3LYP (the default) and PBE0. Both use the same basis sets and are calibrated against the same DELTA50 benchmark, so either gives publication-quality shifts. They differ only in the functional and in where the geometry is optimized.
B3LYP (b3lyp, default) | PBE0 (pbe0) | |
|---|---|---|
| Geometry optimization | B3LYP/6-31G*, gas phase | PBE0/6-31G*, COSMO in the chosen solvent |
| NMR shielding | GIAO B3LYP/6-311+G(2d,p), COSMO | GIAO PBE0/6-311+G(2d,p), COSMO |
| 1H MAE, CDCl3 | 0.06 ppm | 0.08 ppm |
| 13C MAE, CDCl3 | 1.86 ppm | 1.71 ppm |
| Wall time | similar | similar |
MAE is the mean absolute error of the DELTA50 regression; the full table for all 12 solvents is in Expected Accuracy. Each preset copies the geometry protocol its scaling factors were fitted on, which is why B3LYP optimizes in the gas phase and PBE0 does not.
Which one to choose:
- B3LYP if 1H shifts matter most, or if you have no preference. It is ahead of or level with PBE0 for 1H in every solvent.
- PBE0 if 13C shifts matter most. It is about 0.15 ppm better for 13C in every solvent.
The preset key (b3lyp or pbe0) is what you pass to the API and in batch CSV files.
Tips for Best Results
Before Submission
- Validate your SMILES - Use the live preview to catch syntax errors
- Match experimental solvent - Use the same solvent as your NMR experiment
- Pick the preset for your nucleus - B3LYP is slightly better for 1H, PBE0 for 13C
Interpreting Results
- Compare spectrum patterns - Overall shape and relative positions matter more than absolute values
- Account for systematic errors - DFT shifts may be uniformly offset from experiment
- Remember single-conformer limits - Highly flexible structures may need external conformer sampling
Performance Tips
- Start with a small molecule - Verify your setup before committing to a large calculation
- Monitor job status - Long-running jobs can be checked via the status page
REST API Reference
The REST API provides programmatic access for automation and integration with other tools.
Overview
| Property | Value |
|---|---|
| Base URL | http://localhost:8000/api/v1 |
| Authentication | Optional ORCID login (session cookie; institutional accounts via ORCID's institutional AAI). Web job submission (/submit) requires login when ORCID is configured. The REST API stays public for anonymous clients; when a session is present, submitted jobs are owned by that user and delete/rerun/reanalyze of owned jobs require the owner. |
| Content-Type | application/json (requests and responses) |
| Workflow | Asynchronous: submit returns 202, poll for completion |
Health Endpoints
Liveness Probe:
curl http://localhost:8000/healthResponse:
{"status": "alive"}Readiness Probe:
curl http://localhost:8000/health/readyResponse:
{
"status": "ready",
"checks": {
"data_directory": "ok",
"task_queue": "ok"
},
"timestamp": "2026-02-01T12:00:00Z"
}If any component is unavailable, returns HTTP 503 with "status": "not ready".
Job Submission
Submit via SMILES (POST /api/v1/jobs):
curl -X POST http://localhost:8000/api/v1/jobs \
-H "Content-Type: application/json" \
-d '{
"smiles": "CCO",
"solvent": "chcl3",
"preset": "b3lyp",
"name": "Ethanol",
"notification_email": null
}'Request body fields:
| Field | Type | Required | Description |
|---|---|---|---|
smiles | string | Yes | SMILES representation of molecule |
solvent | string | Yes | NMR solvent (see README for all 13 codes, e.g., chcl3, dmso, acetonitrile) |
preset | string | No | b3lyp or pbe0 (default: b3lyp); see Calculation Presets |
name | string | No | Optional molecule label (max 100 chars) |
notification_email | string | No | Email for completion notification |
Response (HTTP 202 Accepted):
{
"job_id": "a1b2c3d4e5f6",
"status": "queued",
"created_at": "2026-02-01T12:00:00Z",
"input_smiles": "CCO",
"input_name": "Ethanol",
"preset": "b3lyp",
"solvent": "chcl3"
}Headers:
Location: /api/v1/jobs/a1b2c3d4e5f6- URL for status pollingRetry-After: 30- Suggested polling interval
Submit via File Upload (POST /api/v1/jobs/upload):
curl -X POST http://localhost:8000/api/v1/jobs/upload \
-F "file=@molecule.mol" \
-F "solvent=chcl3" \
-F "preset=b3lyp"Accepts .mol and .sdf files with a single molecule. Returns same response format as SMILES submission.
List Available Solvents (GET /api/v1/jobs/solvents):
curl http://localhost:8000/api/v1/jobs/solventsResponse:
["acetone", "acetonitrile", "benzene", "chcl3", "dcm", "dmf", "dmso", "methanol", "pyridine", "thf", "toluene", "vacuum", "water"]Job Status
Get Job Status (GET /api/v1/jobs/{job_id}):
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6Response varies by job status:
Queued job:
{
"job_id": "a1b2c3d4e5f6",
"status": "queued",
"created_at": "2026-02-01T12:00:00Z",
"started_at": null,
"current_step": null,
"steps_completed": []
}Running job:
{
"job_id": "a1b2c3d4e5f6",
"status": "running",
"created_at": "2026-02-01T12:00:00Z",
"started_at": "2026-02-01T12:00:05Z",
"current_step": "geometry_optimization",
"current_step_label": "Geometry Optimization",
"step_started_at": "2026-02-01T12:00:05Z",
"steps_completed": []
}Complete job:
{
"job_id": "a1b2c3d4e5f6",
"status": "complete",
"completed_at": "2026-02-01T12:15:00Z",
"nmr_results": {
"h1_shifts": [
{"index": 1, "atom": "H", "shift": 3.65},
{"index": 2, "atom": "H", "shift": 1.18}
],
"c13_shifts": [
{"index": 1, "atom": "C", "shift": 57.8},
{"index": 2, "atom": "C", "shift": 18.2}
],
"functional": "b3lyp",
"basis_set": "6-311+G(2d,p)",
"solvent": "chcl3",
"scaling_factor_source": "DELTA50",
"h1_expected_mae": "+/- 0.12 ppm",
"c13_expected_mae": "+/- 1.95 ppm"
}
}Failed job:
{
"job_id": "a1b2c3d4e5f6",
"status": "failed",
"error_message": "NWChem geometry optimization failed: SCF did not converge"
}Polling pattern:
# Poll every 30 seconds until complete
while true; do
STATUS=$(curl -s http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6 | jq -r '.status')
echo "Status: $STATUS"
if [ "$STATUS" = "complete" ] || [ "$STATUS" = "failed" ]; then
break
fi
sleep 30
doneResults Retrieval
All result endpoints require status=complete. Returns HTTP 409 if job is still running.
NMR Shifts (GET /api/v1/jobs/{job_id}/results):
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6/resultsResponse:
{
"h1_shifts": [
{"index": 1, "atom": "H", "shift": 3.65},
{"index": 2, "atom": "H", "shift": 1.18}
],
"c13_shifts": [
{"index": 1, "atom": "C", "shift": 57.8},
{"index": 2, "atom": "C", "shift": 18.2}
],
"functional": "b3lyp",
"basis_set": "6-311+G(2d,p)",
"solvent": "chcl3",
"scaling_factor_source": "DELTA50",
"h1_expected_mae": "+/- 0.12 ppm",
"c13_expected_mae": "+/- 1.95 ppm"
}Optimized Geometry (XYZ format):
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6/geometry \
-o ethanol_optimized.xyzOptimized Geometry (SDF format with bonds):
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6/geometry.sdf \
-o ethanol_optimized.sdf3D Viewer Data (JSON with SDF + shift assignments):
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6/geometry.jsonResponse includes XYZ, SDF, and atom-to-shift mappings for 3D visualization.
Raw NWChem Output (ZIP archive):
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6/output \
-o nwchem_output.zipSpectrum Images:
# 1H NMR spectrum
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6/spectrum/1h.png -o spectrum_1h.png
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6/spectrum/1h.svg -o spectrum_1h.svg
# 13C NMR spectrum
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6/spectrum/13c.png -o spectrum_13c.png
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6/spectrum/13c.svg -o spectrum_13c.svgAnnotated Structure Images:
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6/structure.png -o structure.png
curl http://localhost:8000/api/v1/jobs/a1b2c3d4e5f6/structure.svg -o structure.svgError Handling
HTTP Status Codes:
| Code | Meaning | Example |
|---|---|---|
| 200 | Success | GET /jobs/{id}/results for complete job |
| 202 | Accepted | POST /jobs (job queued) |
| 404 | Not Found | Job ID doesn't exist |
| 409 | Conflict | Requesting results for incomplete job |
| 422 | Validation Error | Invalid SMILES or solvent |
Error Response Format (RFC 7807 Problem Details):
{
"type": "https://qm-nmr-calc.example/problems/invalid-smiles",
"title": "Invalid SMILES String",
"status": 422,
"detail": "RDKit failed to parse SMILES: 'invalid-smiles'"
}Common error types:
invalid-smiles- SMILES string could not be parsedinvalid-solvent- Unknown solvent nameinvalid-file-type- Uploaded file is not .mol or .sdfjob-not-found- No job exists with that IDjob-not-complete- Results requested before job finished
Complete Workflow Example
This bash script submits a job, polls for completion, and downloads all results:
#!/bin/bash
# nmr_calculate.sh - Submit NMR calculation and download results
# Usage: ./nmr_calculate.sh "CCO" "ethanol"
SMILES="$1"
NAME="${2:-molecule}"
BASE_URL="http://localhost:8000"
TIMEOUT=3600 # 1 hour max
# Submit job
echo "Submitting $NAME ($SMILES)..."
RESPONSE=$(curl -s -X POST "$BASE_URL/api/v1/jobs" \
-H "Content-Type: application/json" \
-d "{\"smiles\": \"$SMILES\", \"solvent\": \"chcl3\", \"preset\": \"b3lyp\", \"name\": \"$NAME\"}")
JOB_ID=$(echo "$RESPONSE" | jq -r '.job_id')
if [ "$JOB_ID" = "null" ]; then
echo "Error: $(echo "$RESPONSE" | jq -r '.detail')"
exit 1
fi
echo "Job ID: $JOB_ID"
# Poll for completion
START_TIME=$(date +%s)
while true; do
STATUS_RESPONSE=$(curl -s "$BASE_URL/api/v1/jobs/$JOB_ID")
STATUS=$(echo "$STATUS_RESPONSE" | jq -r '.status')
STEP=$(echo "$STATUS_RESPONSE" | jq -r '.current_step_label // "Waiting"')
echo "Status: $STATUS - $STEP"
if [ "$STATUS" = "complete" ]; then
echo "Calculation complete!"
break
elif [ "$STATUS" = "failed" ]; then
ERROR=$(echo "$STATUS_RESPONSE" | jq -r '.error_message')
echo "Job failed: $ERROR"
exit 1
fi
# Check timeout
ELAPSED=$(($(date +%s) - START_TIME))
if [ $ELAPSED -gt $TIMEOUT ]; then
echo "Timeout after $TIMEOUT seconds"
exit 1
fi
sleep 30
done
# Download results
mkdir -p "results_$NAME"
cd "results_$NAME"
echo "Downloading results..."
curl -s "$BASE_URL/api/v1/jobs/$JOB_ID/results" > nmr_shifts.json
curl -s "$BASE_URL/api/v1/jobs/$JOB_ID/geometry" -o optimized.xyz
curl -s "$BASE_URL/api/v1/jobs/$JOB_ID/geometry.sdf" -o optimized.sdf
curl -s "$BASE_URL/api/v1/jobs/$JOB_ID/spectrum/1h.png" -o spectrum_1h.png
curl -s "$BASE_URL/api/v1/jobs/$JOB_ID/spectrum/13c.png" -o spectrum_13c.png
curl -s "$BASE_URL/api/v1/jobs/$JOB_ID/output" -o nwchem_output.zip
# Display shifts
echo ""
echo "1H Chemical Shifts:"
jq -r '.h1_shifts[] | " H\(.index): \(.shift) ppm"' nmr_shifts.json
echo ""
echo "13C Chemical Shifts:"
jq -r '.c13_shifts[] | " C\(.index): \(.shift) ppm"' nmr_shifts.json
echo ""
echo "Results saved to results_$NAME/"Result Interpretation
Understanding how to interpret NMR calculation results is essential for making effective use of predicted chemical shifts.
Chemical Shift Tables
The results page displays separate tables for 1H and 13C chemical shifts:
1H (Proton) Shifts:
- Typical range: 0-12 ppm for most organic molecules
- Downfield shifts (higher ppm): deshielded protons near electronegative atoms
- Upfield shifts (lower ppm): shielded protons in alkyl groups
- TMS reference: all shifts are relative to tetramethylsilane (0.0 ppm)
13C (Carbon) Shifts:
- Typical range: 0-220 ppm
- Carbonyl carbons: 160-220 ppm
- Aromatic/alkene carbons: 100-160 ppm
- Alkyl carbons: 0-60 ppm
- TMS reference: relative to tetramethylsilane (0.0 ppm)
Atom Indexing:
- Indices (H1, H2, C1, C2...) correspond to the canonical SMILES atom order
- For complex molecules, compare with the 3D viewer where shift labels are overlaid on atoms
Expected Accuracy
The calculator provides Mean Absolute Error (MAE) estimates based on the DELTA50 benchmark dataset:
| Preset | 1H MAE | 13C MAE |
|---|---|---|
| B3LYP | 0.06-0.07 ppm | 1.6-2.1 ppm |
| PBE0 | 0.07-0.08 ppm | 1.5-2.0 ppm |
Ranges span the 12 supported solvents; see Calculation Presets.
Factors affecting accuracy:
- Molecule class: MAE values derived from typical organic molecules; unusual functional groups may differ
- Conformational flexibility: Single-conformer predictions may degrade for very flexible molecules
- Solvent matching: Use the same solvent as your experimental NMR
- Scaling factors: Applied automatically using DELTA50 regression parameters
Interpreting MAE:
- The displayed
+/- X.XX ppmindicates typical deviation from experimental values - Individual atom shifts may deviate more or less than the average
- Relative shift ordering is often more reliable than absolute values
Spectrum Visualizations
The simulated spectra provide a visual representation of predicted NMR patterns:
Spectrum Features:
- X-axis: Chemical shift in ppm (reversed: high to low, left to right)
- Y-axis: Relative intensity (arbitrary units)
- Peak shape: Lorentzian line broadening centered at each predicted shift
- 1H spectrum: Typically displayed 0-12 ppm range
- 13C spectrum: Typically displayed 0-220 ppm range
Using Spectra:
- Compare overall pattern with experimental spectrum
- Peak positions should align within expected MAE
- Relative spacing between peaks is often more reliable than absolute positions
- Click spectrum images in web UI to enlarge
Download Options:
- PNG (300 DPI): Good for presentations and documents
- SVG: Vector format, ideal for publications and scaling
3D Structure Viewer
The interactive 3D viewer displays the optimized molecular geometry with shift labels:
Viewer Controls:
- Rotate: Click and drag
- Zoom: Scroll wheel
- Reset view: Double-click
Shift Labels:
- Blue labels: 1H chemical shifts in ppm
- Orange labels: 13C chemical shifts in ppm
- Labels positioned near corresponding atoms
- Ball-and-stick model with Jmol-style element colors
Downloading Results
Recommended file formats for different purposes:
| Purpose | Format | Why |
|---|---|---|
| Further calculations | XYZ | Universal, simple coordinates |
| Visualization tools | SDF | Contains bonds, opens in ChemDraw/Avogadro |
| Publications | SVG | Vector graphics, scales without pixelation |
| Presentations | PNG | Raster format, widely compatible |
| Reproducibility | ZIP | Full NWChem output for debugging |
Structure files:
- XYZ: Cartesian coordinates only (element + x, y, z)
- SDF: Includes bond connectivity from original SMILES
Troubleshooting Results
Unexpected chemical shifts:
- Check solvent matches your experimental conditions
- Verify SMILES correctly represents your structure
- Consider that some functional groups have higher errors
Missing atoms in 3D viewer:
- Ensure SMILES includes all atoms (explicit hydrogens if needed)
- Check for disconnected fragments in SMILES
Large MAE values:
- Normal for unusual functional groups (phosphorus, sulfur, halogens)
- Consider that benchmark MAE was derived from specific molecule types
- Use relative shift ordering rather than absolute values
Calculation failures:
- Very large molecules may exceed memory limits
- Unusual bonding patterns may fail geometry optimization
- Check NWChem output (ZIP download) for specific error messages
For detailed methodology and scientific references, see the Science documentation.
Related Documentation
- Installation Guide - System setup and dependencies
- Architecture - System design and implementation details
- Science - NMR methodology, DP4+ probability, and references