System Types

MDFactory supports three system-building strategies. Each uses different Pydantic composition models and build functions.

Mixed Box

Creates a homogeneous mixture of molecules in a rectangular box. Molecules are packed to a target density using OpenMM compression.

Use cases

• Solution simulations (solvent + solute)
• Polymer blends
• Small molecule mixtures
• Bulk liquid properties

Configuration

engine: gromacs
simulation_type: mixedbox
parametrization: smirnoff

system:
  species:
    - smiles: "O"
      resname: SOL
      count: 900
    - smiles: "CCO"
      resname: ETH
      count: 100
  target_density: 1.0
  ionization:
    neutralize: true
    concentration: 0.15

MixedBoxComposition fields

Tips

• Use count for absolute molecule numbers or fraction for molar ratios (with total_count)
• target_density determines the box size — no need to specify box dimensions
• Fractions must sum to 1.0 across all species

Bilayer

Builds lipid bilayer systems with water on both sides. Uses OpenMM compression to assemble the bilayer structure, then solvates and ionizes.

Use cases

• Membrane simulations
• Lipid phase behavior
• Drug permeation studies
• Bilayer property calculations (APL, order parameters, thickness)

Configuration

engine: gromacs
simulation_type: bilayer
parametrization: cgenff

system:
  species:
    - smiles: "CCCCCCCCCCCCCCCC(=O)OC[C@H](COP(=O)([O-])OCC[N+](C)(C)C)OC(=O)CCCCCCC/C=C\\CCCCCCCC"
      resname: POPC
      count: 128
      head_atoms: [32, 33, 34, 35, 36, 37, 38, 39, 40, 41]
      tail_atoms: []
  z_padding: 20.0
  monolayer: false
  ionization:
    neutralize: true
    concentration: 0.15

BilayerComposition fields

LipidSpecies fields

Tips

• Lipid count must be even for bilayers (split between leaflets)
• head_atoms and tail_atoms are auto-detected from SMILES if not provided
• Use monolayer: true for monolayer systems

Lipid Nanoparticle (LNP)

Builds spherical lipid nanoparticle systems with a hydrophobic core and lipid monolayer shell. The build process creates the core and shell separately, merges them, then solvates with spherical exclusion and ionizes.

Use cases

• mRNA vaccine delivery vehicles
• Drug encapsulation and delivery
• Ionizable lipid formulations
• PEGylated nanoparticle systems

Configuration

engine: gromacs
simulation_type: lnp
parametrization: smirnoff

system:
  radius: 60.0
  shell_thickness: 28.0
  padding: 25.0

  core:
    species:
      - smiles: "IONIZABLE_LIPID_SMILES"
        resname: ILN
        fraction: 0.4
      - smiles: "CHOLESTEROL_SMILES"
        resname: CHL
        fraction: 0.6
    target_density: 0.95
    replication_factor: 1

  shell:
    species:
      - smiles: "DSPC_SMILES"
        resname: DSP
        fraction: 0.5
      - smiles: "PEG_LIPID_SMILES"
        resname: PEG
        fraction: 0.5
    z0: 10.0
    area_per_lipid: 65.0

  ionization:
    neutralize: true
    concentration: 0.15

LNPComposition fields

CoreComposition fields

ShellComposition fields

Tips

• Core species must all use fraction (not count), and fractions must sum to 1.0
• Shell species must also use fraction summing to 1.0
• core_radius is computed as radius - shell_thickness
• Molecule counts are calculated automatically from the geometry and density
• Include both neutral and protonated forms of ionizable lipids as separate species

IonizationConfig (shared)

All system types support ionization configuration:

SingleMoleculeSpecies fields (shared)

Either count or fraction must be provided (not both).

Choosing a system type

Next steps