USER_MATERIALS_GUIDE.md

User-Defined Materials Feature Guide

Overview

The GDML Editor now includes a comprehensive user-defined materials system that allows you to create, manage, and use custom materials in your geometry files. Materials are stored in a persistent database and can be used across multiple GDML files.

Features

1. Material Database

• Materials are stored in ~/.gdml_editor/user_materials.json
• Persistent storage across sessions
• Easy backup and sharing (just copy the JSON file)

2. Material Types

Compound Materials

Define materials using molecular formulas:

• Example formulas: H2O, SiO2, CaCO3, PbF2, Al2O3
• Automatically calculates element ratios from formula
• Ideal for pure chemical compounds

Mixture Materials

Define materials by mass fraction of elements:

• Specify each element and its mass fraction
• Fractions must sum to 1.0
• Ideal for alloys, composites, and complex mixtures

3. Material Properties

Required Properties:

• Name: Unique identifier for the material
• Density: Material density with units (g/cm³, mg/cm³, or kg/m³)
• Composition: Either molecular formula (compound) or element fractions (mixture)

Optional Properties (Hidden by Default):

• State: solid, liquid, or gas (default: solid)
• Temperature: With units (K or °C)
• Pressure: With units (pascal, bar, or atm)

Usage Guide

Creating a New Material

1. From Menu Bar:

   • Go to Materials → Define New Material...

2. Fill in Material Details:

   • Enter a unique material name
   • Select material type (Compound or Mixture)
   • Enter density and select units

3. Define Composition:

   For Compound Materials:

   • Enter molecular formula (e.g., H2O, SiO2, CaCO3)
   • Formula parser automatically determines element ratios

   For Mixture Materials:

   • Add elements using "Add Element" button
   • Enter element symbol and mass fraction for each
   • Mass fractions must sum to 1.0
   • Use "Remove" button to delete element rows

4. Optional Advanced Properties (click checkbox to show):

   • Set state (solid/liquid/gas)
   • Specify temperature
   • Specify pressure

5. Save: Click "Save Material" button

Using User Materials

1. Open a GDML file
2. Select a volume from the tree
3. In the Volume Properties panel (right side):
   • Use the Material dropdown to select your user material
   • Click Apply

Notes:

• The material dropdown is a combined list of registry materials, Geant4/NIST G4_... names, and your user-defined materials.
• If a selected material is not yet in the loaded registry, it is created on-demand and added before applying.

Managing Materials

Access material management via Materials → Manage User Materials...:

• View: Click on any material to see its details
• Edit: Select a material and click "Edit Selected"
• Delete: Select a material and click "Delete Selected"
• Create: Click "New Material" to add another

Examples

Example 1: Water (Compound)

Name: Water
Type: Compound
Density: 1.0 g/cm³
Formula: H2O
State: liquid

Example 2: Borosilicate Glass (Compound)

Name: BorosilicateGlass
Type: Compound
Density: 2.23 g/cm³
Formula: B2O3SiO2
State: solid

Example 3: Stainless Steel 316 (Mixture)

Name: StainlessSteel316
Type: Mixture
Density: 8.0 g/cm³
Composition:
  Fe: 0.68
  Cr: 0.17
  Ni: 0.12
  Mo: 0.03
State: solid

Example 4: Custom Scintillator (Mixture)

Name: CustomScintillator
Type: Mixture
Density: 1.032 g/cm³
Composition:
  H: 0.0854
  C: 0.9146
State: solid
Temperature: 293.15 K
Pressure: 101325 pascal

Example 5: Lead Fluoride Crystal (Compound)

Name: LeadFluoride
Type: Compound
Density: 7.77 g/cm³
Formula: PbF2
State: solid

Technical Details

Formula Parsing

Compound formulas are parsed to extract elements and their stoichiometric ratios:

• Element symbols are case-sensitive (H, He, Li, etc.)
• Numbers follow element symbols (H2O → 2 hydrogen, 1 oxygen)
• Parentheses are supported for complex formulas

Unit Conversions

The system automatically converts units to Geant4/GDML standards:

• Density: All units converted to g/cm³
• Temperature: Celsius converted to Kelvin
• Pressure: bar and atm converted to pascal

Material Creation

When applying a user material to a volume:

1. System checks if material exists in registry
2. If not, creates material using pyg4ometry
3. For compounds: Uses MaterialCompound class
4. For mixtures: Uses Material class with element mass fractions
5. Material is added to registry and becomes available

Database Format

Materials are stored in JSON format at ~/.gdml_editor/user_materials.json:

{
  "MaterialName": {
    "type": "compound",
    "density": 2.5,
    "density_unit": "g/cm3",
    "composition": "SiO2",
    "state": "solid"
  }
}

Tips and Best Practices

1. Naming Convention: Use descriptive names without spaces
2. Backup Database: Regularly backup ~/.gdml_editor/user_materials.json
3. Share Materials: Copy the JSON file to share materials with colleagues
4. Verify Formulas: Double-check molecular formulas for accuracy
5. Mass Fractions: Ensure mixture fractions sum to exactly 1.0
6. Element Symbols: Use correct element symbols (case-sensitive)
7. Density Units: Match units to your source data for accuracy

Troubleshooting

Material Not Created

• Check formula syntax for compounds
• Verify element symbols are correct
• Ensure mass fractions sum to 1.0 for mixtures

Element Not Found

• Use standard element symbols (H, He, Li, C, N, O, etc.)
• Check for typos in element names
• Ensure elements exist in NIST database

Density Issues

• Verify density value is positive
• Check unit selection matches your data
• Consider material state when specifying density

Integration with GDML

User materials are fully integrated with the GDML workflow:

1. Materials are created in the pyg4ometry registry
2. Can be assigned to any logical volume
3. Saved with geometry when exporting GDML
4. Materials persist in the GDML file for later use

Future Enhancements

Potential future additions:

• Import materials from external databases
• Export material definitions
• Optical properties support
• Material templates library
• Batch material creation