generate¶

One-shot convenience function composing the three pipeline stages (GeometryBuilder → UnitTyper → BoxPacker). Use the stage classes directly when you need control between stages (e.g. typing one geometry under multiple force fields); use generate() for single-force-field one-shot runs.

Beyond the bulk-melt default, generate() also accepts:

substrate=SubstrateSpec(...) — build a film on a physical substrate slab (auto-selects the on_substrate strategy);
subtract=[CutAbove(...) / Cylinder(...) / ...] — whole-instance carve regions applied after placement;
box_dims=(lx, ly, lz) — rectangular boxes (per-axis auto-sizing with None).

See the Substrates & Films guide for the full surface-simulation workflow.

`AutoPoly.pipeline.workflow` ¶

Workflow Convenience Function for AutoPoly Package

This module provides :func:generate, a thin one-shot convenience function that composes the three pipeline stages:

GeometryBuilder  (stage 1: FF-agnostic coordinates -> geometry/)
UnitTyper        (stage 2: force-field typing      -> build/<ff>/)
BoxPacker        (stage 3: box packing + moltemplate -> moltemplate/)

All stage logic lives in the stage modules (geometry.py, typing.py, packer.py, packing/). Use the stage classes directly when you need control between stages (e.g. typing one geometry under multiple force fields); use generate() when a single force field one-shot run is all you need.

Created on 2026-01-06 @author: zwu

Functions:

Name	Description
`generate`	Generate a complete LAMMPS system in one call (three-stage pipeline).

`generate(system: object, name: str, models: List[object], force_field: str = 'oplsaa', *, strategy: str = 'mc_random', geometry_config: Optional[GeometryConfig] = None, box_size: Optional[float] = None, mc_max_attempts: int = 10000, monomer_density: float = 0.085, rng_seed: Optional[int] = None, run_moltemplate: bool = True, substrate: Optional[SubstrateSpec] = None, subtract: Optional[list] = None, box_dims: Optional[tuple] = None) -> PlacementResult` ¶

Generate a complete LAMMPS system in one call (three-stage pipeline).

Runs GeometryBuilder -> UnitTyper -> BoxPacker, producing:

<out>/<name>/geometry/geometry.json
<out>/<name>/build/<ff>/*.lt + units.json
<out>/<name>/moltemplate/system.lt -> moltemplate -> system.data etc.

Parameters:

Name	Type	Description	Default
`system`	`object`	System object providing get_folder_path().	required
`name`	`str`	Project name; outputs go to `<out>/<name>/`.	required
`models`	`List[object]`	List of Polymer and/or Molecule objects (the "film" models when a substrate is used).	required
`force_field`	`str`	Force field name (see FORCE_FIELD_REGISTRY). Defaults to "oplsaa".	`'oplsaa'`
`strategy`	`str`	Box packing strategy ("mc_random", "grid", "on_substrate", ...). Defaults to "mc_random". When `substrate` is given and strategy is left at its default, "on_substrate" is selected automatically.	`'mc_random'`
`geometry_config`	`Optional[GeometryConfig]`	Optional GeometryConfig for stage 1 (MC chain growth parameters). Defaults to GeometryConfig().	`None`
`box_size`	`Optional[float]`	Optional explicit box edge length (Angstrom) for stage 3.	`None`
`mc_max_attempts`	`int`	Maximum placement attempts for MC placement. Defaults to 10000.	`10000`
`monomer_density`	`float`	Target monomer density (monomers/A^3) for MC box sizing. Defaults to 0.085.	`0.085`
`rng_seed`	`Optional[int]`	Optional RNG seed for reproducible placement.	`None`
`run_moltemplate`	`bool`	Run moltemplate at the end of stage 3. Defaults to True.	`True`
`substrate`	`Optional[SubstrateSpec]`	Optional SubstrateSpec describing a physical substrate slab; film models are packed on top of it. Selects the "on_substrate" strategy automatically.	`None`
`subtract`	`Optional[list]`	Optional list of CarveRegion specs (CutAbove, Cylinder, ...) removing whole instances after placement. Supported by "mc_random" and "on_substrate".	`None`
`box_dims`	`Optional[tuple]`	Optional per-axis box sides (lx, ly, lz) in Angstrom; any element may be None (auto-sized). Overrides box_size per axis where given.	`None`

Returns:

Type	Description
`PlacementResult`	PlacementResult from the packing stage.

Raises:

Type	Description
`WorkflowError`	If any critical step fails or required files are missing
`ValidationError`	On contradictory strategy/substrate/subtract combinations or unresolvable substrate counts.

Example

from AutoPoly import System, Polymer, generate system = System(out="pmma_out") polymer = Polymer(chain_num=4, sequence=sequence, ... topology="linear", tacticity="atactic") generate(system, "pmma", [polymer], force_field="oplsaa")

Film on a substrate slab:¶

from AutoPoly.packing import SubstrateSpec spec = SubstrateSpec(model=Molecule(Count=200, Smiles="O=[Si]=O", ... Name="sio2"), ... thickness=15.0, packing="grid", gap=3.0) generate(system, "pmma_on_sio2", [polymer], ... substrate=spec, box_dims=(60.0, 60.0, None))

Source code in AutoPoly/pipeline/workflow.py

def generate(
    system: object,
    name: str,
    models: List[object],
    force_field: str = "oplsaa",
    *,
    strategy: str = "mc_random",
    geometry_config: Optional[GeometryConfig] = None,
    box_size: Optional[float] = None,
    mc_max_attempts: int = 10000,
    monomer_density: float = 0.085,
    rng_seed: Optional[int] = None,
    run_moltemplate: bool = True,
    substrate: Optional[SubstrateSpec] = None,
    subtract: Optional[list] = None,
    box_dims: Optional[tuple] = None,
) -> PlacementResult:
    """
    Generate a complete LAMMPS system in one call (three-stage pipeline).

    Runs GeometryBuilder -> UnitTyper -> BoxPacker, producing:

    - ``<out>/<name>/geometry/geometry.json``
    - ``<out>/<name>/build/<ff>/*.lt`` + ``units.json``
    - ``<out>/<name>/moltemplate/system.lt`` -> moltemplate -> ``system.data`` etc.

    Args:
        system: System object providing get_folder_path().
        name: Project name; outputs go to ``<out>/<name>/``.
        models: List of Polymer and/or Molecule objects (the "film" models
            when a substrate is used).
        force_field: Force field name (see FORCE_FIELD_REGISTRY).
            Defaults to "oplsaa".
        strategy: Box packing strategy ("mc_random", "grid",
            "on_substrate", ...). Defaults to "mc_random". When
            ``substrate`` is given and strategy is left at its default,
            "on_substrate" is selected automatically.
        geometry_config: Optional GeometryConfig for stage 1 (MC chain
            growth parameters). Defaults to GeometryConfig().
        box_size: Optional explicit box edge length (Angstrom) for stage 3.
        mc_max_attempts: Maximum placement attempts for MC placement.
            Defaults to 10000.
        monomer_density: Target monomer density (monomers/A^3) for MC box
            sizing. Defaults to 0.085.
        rng_seed: Optional RNG seed for reproducible placement.
        run_moltemplate: Run moltemplate at the end of stage 3.
            Defaults to True.
        substrate: Optional SubstrateSpec describing a physical substrate
            slab; film models are packed on top of it. Selects the
            "on_substrate" strategy automatically.
        subtract: Optional list of CarveRegion specs (CutAbove, Cylinder,
            ...) removing whole instances after placement. Supported by
            "mc_random" and "on_substrate".
        box_dims: Optional per-axis box sides (lx, ly, lz) in Angstrom;
            any element may be None (auto-sized). Overrides box_size per
            axis where given.

    Returns:
        PlacementResult from the packing stage.

    Raises:
        WorkflowError: If any critical step fails or required files are missing
        ValidationError: On contradictory strategy/substrate/subtract
                         combinations or unresolvable substrate counts.

    Example:
        >>> from AutoPoly import System, Polymer, generate
        >>> system = System(out="pmma_out")
        >>> polymer = Polymer(chain_num=4, sequence=sequence,
        ...                   topology="linear", tacticity="atactic")
        >>> generate(system, "pmma", [polymer], force_field="oplsaa")

        >>> # Film on a substrate slab:
        >>> from AutoPoly.packing import SubstrateSpec
        >>> spec = SubstrateSpec(model=Molecule(Count=200, Smiles="O=[Si]=O",
        ...                                   Name="sio2"),
        ...                      thickness=15.0, packing="grid", gap=3.0)
        >>> generate(system, "pmma_on_sio2", [polymer],
        ...          substrate=spec, box_dims=(60.0, 60.0, None))
    """
    try:
        logger.info("Starting LAMMPS data file generation using Moltemplate")

        strategy = _resolve_strategy(strategy, substrate, subtract)
        substrate_models = _resolve_substrate_models(substrate, box_dims)

        # Stage 1: force-field-agnostic geometry
        geometry_result = GeometryBuilder(
            system, name, config=geometry_config
        ).build(models, substrate_models=substrate_models)

        # Stage 2: force-field typing on the stored geometry
        units = UnitTyper(geometry_result.dir, force_field).type()

        # Stage 3: box packing + moltemplate
        result = BoxPacker(
            system,
            name,
            strategy=strategy,
            box_size=box_size,
            mc_max_attempts=mc_max_attempts,
            monomer_density=monomer_density,
            rng_seed=rng_seed,
            run_moltemplate=run_moltemplate,
            substrate=substrate,
            subtract=subtract,
            box_dims=box_dims,
        ).pack(units)

        logger.info("Successfully completed polymer generation")
        return result

    except Exception as e:
        raise WorkflowError(
            f"Error in generate: {str(e)}"
        ) from e

generate¶

AutoPoly.pipeline.workflow ¶

Film on a substrate slab:¶

`AutoPoly.pipeline.workflow` ¶