PetroPyQAPF User Manual

Introduction

What is PetroPyQAPF?

PetroPyQAPF is a Python desktop application designed to support reproducible igneous rock classification and technical reporting. The software separates the formal modal decision from geochemical contrast, probabilistic support, interpretive synthesis, mineral reference, petrographic image review, and report presentation.

Who Should Use PetroPyQAPF?

• Students learning igneous petrology and rock classification
• Geologists conducting petrographic analysis in academic research
• Teachers demonstrating IUGS-QAPF classification methods
• Researchers requiring reproducible and traceable classification workflows

Installation & Setup

System Requirements

• Windows 10/11 (64-bit)
• 4 GB RAM minimum (8 GB recommended)
• 500 MB available disk space
• Microsoft Word (for PDF report generation)
• Internet connection (for authentication and optional AI features)

Installation Steps

1. Download the latest release from the official website
2. Extract the ZIP file to your preferred location
3. Run PetroPyQAPF.exe from the extracted folder
4. On first launch, authenticate with your academic Google account
5. Select your preferred language (Spanish or English)

Authentication

PetroPyQAPF uses Google/Firebase authentication to verify academic access. Only authorized email addresses can run the application. Authentication does not transmit samples, chemical data, or generated reports—it only validates your access credentials.

Getting Started

Creating Your First Project

1. Launch PetroPyQAPF
2. Click "New Project" in the main menu
3. Enter a project name and optional description
4. Choose between Manual Entry or Import from CSV/Excel

Manual Sample Entry

For individual sample classification:

1. Click "Add Sample"
2. Enter sample identification (name, location, date)
3. Select domain: Plutonic or Volcanic
4. Input modal mineralogy (Q, A, P, F percentages)
5. Optionally add auxiliary petrographic data (M, Pl, An, Px, Ol, Anf)
6. Optionally input major oxide geochemistry for CIPW comparison

Batch Import from CSV/Excel

For multiple samples:

1. Prepare your data file with columns: Sample_ID, Q, A, P, F, Domain
2. Click "Import Batch"
3. Select your CSV or Excel file
4. Map columns to PetroPyQAPF fields
5. Review and confirm imported samples

Modal Classification

Understanding IUGS-QAPF Logic

The IUGS-QAPF system classifies igneous rocks based on the relative proportions of four mineral groups:

• Q - Quartz and quartz-equivalent minerals
• A - Alkali feldspars (orthoclase, microcline, sanidine, etc.)
• P - Plagioclase feldspars
• F - Feldspathoids (nepheline, leucite, etc.)

Domain Selection

PetroPyQAPF separates plutonic (coarse-grained, intrusive) and volcanic (fine-grained, extrusive) domains. Each domain has specific nomenclature:

• Plutonic: Granite, Granodiorite, Tonalite, Diorite, Gabbro, etc.
• Volcanic: Rhyolite, Dacite, Andesite, Basalt, Trachyte, etc.

Specialized Routing

For rocks outside the standard QAPF range:

• Ultramafic rocks (M > 90%): Uses Ol-Opx-Cpx ternary diagrams
• Gabbroic rocks: Specialized Pl-Px-Ol and Pl-Px-Anf ternaries
• Foidolite classification: For F-rich feldspathoid-bearing rocks

Interpretation of Results

After entering modal data, PetroPyQAPF provides:

• Official rock name from IUGS-QAPF position
• Position coordinates within the ternary diagram
• Validation warnings if data quality or consistency issues are detected
• Alternative names for boundary cases

CIPW Normative Comparison

What is CIPW?

The CIPW norm calculates an idealized, anhydrous mineral assemblage from whole-rock geochemical data. It provides a secondary compositional perspective that complements modal observation.

Entering Oxide Data

Input major oxide percentages (wt%):

• SiO₂, TiO₂, Al₂O₃, Fe₂O₃, FeO, MnO, MgO, CaO, Na₂O, K₂O, P₂O₅

Modal vs. CIPW Comparison

PetroPyQAPF projects CIPW normative minerals onto the QAPF diagram and calculates:

• Distance: Euclidean distance between modal and normative positions
• Consistency level: High, Moderate, or Low agreement
• Warnings: Flags for significant discrepancies that may indicate alteration, analytical issues, or magmatic complexity

Why Modal and CIPW May Differ

• Alteration: Weathering or hydrothermal alteration changes mineral chemistry
• Magmatic history: Cumulate textures, crystal fractionation, or mixing
• Analytical uncertainty: Errors in modal counting or geochemical analysis
• CIPW assumptions: The norm assumes idealized equilibrium conditions

Machine Learning Support

ML Model Architecture

PetroPyQAPF uses domain-specific ML models trained on regional geochemical datasets:

• Volcanic domain: XGBoost classifier
• Plutonic domain: Random Forest classifier

Reading ML Output

For each sample, the ML layer provides:

• Top prediction: Most probable rock class based on geochemistry
• Confidence score: Probability of the top prediction (0-100%)
• Alternative classes: Second and third most likely classes with scores
• Agreement indicator: Whether ML prediction matches modal classification

When ML Disagrees with Modal

If ML and modal classifications differ significantly:

1. Review modal counting accuracy
2. Check for alteration or weathering
3. Verify oxide analytical quality
4. Consider magmatic complexity (mixing, cumulates)
5. Consult the NIM interpretation for context

Normalized Interpretation Model (NIM)

What is NIM?

NIM synthesizes evidence from modal, CIPW, and ML layers into a coherent interpretation. It quantifies:

• Support level: Agreement across classification methods
• Uncertainty: Confidence in the formal classification
• Evidence factors: Weights for modal, geochemical, and probabilistic data
• Recommendations: Suggested follow-up actions (recount, re-analyze, etc.)

Support Levels

• High: All methods agree; classification is robust
• Moderate: Some disagreement; review recommended
• Low: Significant conflicts; petrographic re-evaluation needed

Using NIM Effectively

NIM does not reclassify rocks. It helps you understand the quality and coherence of your classification. Use NIM recommendations to prioritize samples for detailed review or re-analysis.

Petrographic Viewer

Loading Photomicrographs

1. Select a sample in your project
2. Click "Attach Image" in the Viewer panel
3. Choose PPL (plane-polarized light) or XPL (cross-polarized light)
4. Browse to your photomicrograph file (JPG, PNG, TIFF)
5. Repeat to load both PPL and XPL images for comparison

Comparison Tools

When both PPL and XPL images are loaded:

• Side-by-side mode: View images next to each other
• Slider mode: Vertical or horizontal divider to compare registered images
• Zoom and pan: Synchronized navigation across both views

Scale Calibration

1. Click "Calibrate Scale"
2. Draw a line across a known diameter (e.g., field of view, scale bar)
3. Enter the actual measurement in micrometers (µm) or millimeters (mm)
4. Measurements and annotations will now display calibrated dimensions

Annotations and Measurements

• Point markers: Identify mineral grains
• Line measurements: Grain size, twin spacing
• Text labels: Annotate mineral names or features
• Area selection: Highlight zones of interest

Capturing for Reports

Click "Capture View" to save the current viewer state (including annotations) as an image. Captured images are automatically included in exported reports.

Mineral Atlas

Accessing the Atlas

Click "Mineral Atlas" in the main toolbar to open the integrated reference guide for rock-forming minerals.

Search and Browse

• Name search: Find minerals by common or systematic names
• Formula search: Search by chemical formula (e.g., SiO₂, CaAl₂Si₂O₈)
• Category filter: Browse by mineral group (feldspars, pyroxenes, amphiboles, etc.)

Mineral Information Cards

Each mineral entry includes:

• Chemical formula and crystal system
• Optical properties: Relief, birefringence, extinction angle, pleochroism
• Common occurrences: Typical rock types and geological settings
• Distinguishing features: Key identification criteria
• Visual references: PPL and XPL photomicrograph examples

Bilingual Support

The mineral atlas is available in Spanish and English. Content automatically switches to match your selected application language.

Reports and Export

Report Generation

1. Select one or more samples in your project
2. Click "Generate Report"
3. Choose report format:
   • JSON: Machine-readable data for archival or integration
   • Text: Plain-text summary for quick review
   • PDF: Formal technical report with diagrams and images

PDF Report Contents

The formal PDF report includes:

• Project and sample metadata
• Modal classification results with QAPF diagram position
• CIPW normative data and comparison metrics
• ML predictions and confidence scores
• NIM interpretation and recommendations
• Petrographic viewer captures (if attached)
• Data tables and validation warnings

Project Package Export

Export your entire project as a ZIP archive containing:

• .gisgeo project file: Full project data in JSON format
• Summary CSV/Excel: Tabular data for all samples
• Individual JSON reports: One per sample
• Attached images: PPL/XPL photomicrographs and captures

Opening Saved Projects

Click "Open Project" and select a .gisgeo file to restore your work. All sample data, images, annotations, and settings are preserved.

AI-Assisted Interpretation (Optional)

Configuring AI Backends

PetroPyQAPF can integrate with AI services for natural-language interpretation:

• Local Ollama: Run models on your own machine
• OpenAI API: GPT-4 or other OpenAI models
• Anthropic API: Claude models

To configure:

1. Open Settings → AI Configuration
2. Select your preferred backend
3. Enter API credentials (if using cloud services)
4. Test connection

Using GPKE (Geological Petrological Knowledge Engine)

GPKE synthesizes modal, geochemical, and probabilistic evidence into natural-language hypotheses:

• Petrogenetic scenarios (magmatic evolution, mixing, contamination)
• Tectonic setting inferences
• Alteration or weathering interpretations
• Quality assessment and data review suggestions

Important Limitations

• AI interpretations are not peer-reviewed scientific conclusions
• GPKE does not reclassify rocks—it provides context and hypotheses
• Always validate AI suggestions against petrographic observations and geological context

Troubleshooting

Authentication Issues

Problem: Cannot log in with Google account

• Verify your email is registered for academic access at /portfolio/petropyqapf/register
• Check internet connection
• Ensure firewall allows PetroPyQAPF to access Firebase servers
• Contact jordanzav@gisgeo.dev if access is denied after registration

Data Import Errors

Problem: CSV/Excel import fails or produces incorrect results

• Verify column headers match expected field names (Q, A, P, F, Domain)
• Check for missing or non-numeric values in mineral percentage columns
• Ensure file encoding is UTF-8 (especially for Spanish characters)
• Use the provided CSV template as a reference

CIPW Calculation Warnings

Problem: CIPW norm fails or shows "Invalid composition"

• Check oxide total: should be 98-102%
• Verify all required oxides are entered (SiO₂, Al₂O₃, FeO, MgO, CaO, Na₂O, K₂O)
• Ensure no negative values or extreme outliers
• Review Fe₂O₃/FeO ratio—both should not be zero

PDF Export Fails

Problem: Cannot generate PDF reports

• Ensure Microsoft Word is installed and activated
• Close any open Word documents before exporting
• Check write permissions for the output directory
• Try exporting to a different folder (avoid system directories)

Petrographic Viewer Issues

Problem: Images won't load or display incorrectly

• Supported formats: JPG, PNG, TIFF, BMP
• Maximum file size: 50 MB per image
• Try reducing image resolution if file is very large
• Verify file path has no special characters

Frequently Asked Questions

Support & Contact

Technical Support

For bugs, feature requests, or technical questions:
Email: jordanzav@gisgeo.dev

Academic Registration

To register for academic access:
Request Academic Access

Commercial Licensing

For enterprise, consulting, or institutional use:
Email: jordanzav@gisgeo.dev

Documentation Updates

This manual is updated with each software release. Check the PetroPyQAPF homepage for the latest version.