Release v. 0.99 - LAMMPS-GUI Ready

🍕 Pizza3 Prerelease: "LAMMPS-GUI Ready" 🚀

Experience the power of Pizza3 with the featured example, example2.py, designed to demonstrate its advanced functionalities.

📦 Available Versions

• Full version: Includes sample dump files for a complete demonstration — Pizza3_v0.99.zip.
• Minimal version: Lightweight, containing only essential files — Pizza3_v0.99min.zip.

🛠️ Test and Explore

🔗 Test the generated LAMMPS code with LAMMPS-GUI for your platform.
📚 Read the online documentation of Pizza3 on GitHub Pages.

---

Comprehensive Documentation: Example 2

Example 2 serves as a showcase of the Pizza3 toolkit, highlighting its robust capabilities for creating, managing, and analyzing LAMMPS simulations. This example demonstrates how to effectively integrate multiple components of the Pizza3 framework, providing a detailed glimpse into its versatility and advanced features.

---

Objective

This example demonstrates the programmatic creation of 3D geometries, management of atomic groups, and generation of both LAMMPS scripts and DSCRIPT files. The goal is to illustrate the flexibility and modularity of the Pizza3 toolkit for handling simulation workflows efficiently and dynamically.

---

What You Will Learn

1. Initialization and Setup:

   • Configure global settings for simulations.
   • Handle directory and file management for temporary data.

2. Using the region Class:

   • Define and initialize a 3D simulation box with SI units.
   • Create subdomains (regions) within the box using a lattice-based approach.
   • Add cylindrical regions with specific dimensions and bead types.

3. Dynamic Group Management with group and groupobject:

   • Create and manage groups of atoms based on bead types.
   • Perform arithmetic operations on groups (union, subtraction).
   • Dynamically assign masses and verify atom counts for each group.

4. Combining Scripts:

   • Use the pipescript class to combine multiple scripts into a cohesive workflow.
   • Modularly add initialization, lattice definitions, group assignments, and geometry preview scripts.

5. Generating and Using DSCRIPT Files:

   • Export LAMMPS scripts to DSCRIPT format for reusability.
   • Reconstruct and validate LAMMPS scripts from DSCRIPT files.

6. Debugging and Visualization:

   • Generate output files for debugging and visualizing the simulation geometry.
   • Use flexible templates and substitutions to manage dynamic variables.

---

Structure of the Script

The script is divided into multiple logical sections, each demonstrating a specific feature of the Pizza3 toolkit:

1. Setup and Directory Management

• Initializes a temporary folder (tmp/) to store generated scripts and output files.
• Ensures the folder exists or creates it dynamically.

2. Defining the Simulation Box

• Creates a simulation box using the region class.
• Configures:
  • Dimensions (3D).
  • Boundary conditions (fixed).
  • Units (SI).
  • Lattice styles and spacing.

3. Adding Subregions

• Adds cylindrical subregions within the simulation box.
• Associates each cylinder with a specific bead type and dimensions.

4. Managing Groups

• Uses the groupobject class to define atom groups for each bead type.
• Combines groups dynamically using operations like union and subtraction.
• Assigns masses to groups and verifies atom counts.

5. Generating Scripts

• Creates modular LAMMPS scripts for initialization, group definitions, and geometry preview.
• Combines them into a single script using pipescript.

6. Exporting and Validating DSCRIPT Files

• Converts the LAMMPS script to a DSCRIPT format for future reuse.
• Loads the DSCRIPT file and regenerates the LAMMPS script to verify consistency.

---

Key Components and Tools

Pizza3 Classes and Methods

Class/Module	Functionality
region	Defines 3D simulation boxes and subregions.
groupobject	Manages groups of atoms or molecules.
group	Performs arithmetic operations on groups and evaluates atom counts.
pipescript	Combines multiple script components into a single executable pipeline.
dscript	Converts LAMMPS scripts into modular, reusable DSCRIPT files.

LAMMPS Integration

• The script generates valid LAMMPS input files with commands for defining regions, groups, and atoms.
• The generated scripts are compatible with LAMMPS' syntax and can be executed directly.

DSCRIPT Features

• Encodes LAMMPS workflows in a structured, modular format.
• Supports dynamic variable substitutions for maximum flexibility.

---

Execution Steps and Python Code

Step 1: Setup and Directory Management

Before beginning, ensure that the required directory structure exists. This example uses a tmp/ directory for storing temporary files.

import os

# Path to the 'tmp' folder
tmp_folder = os.path.join(os.getcwd(), "tmp")
allow_create = True  # Set to False to prevent automatic creation

# Check and create the folder if necessary
if not os.path.exists(tmp_folder):
    if allow_create:
        os.makedirs(tmp_folder)
        print(f"Created temporary folder: {tmp_folder}")
    else:
        raise FileNotFoundError(
            f"\n\nThe 'tmp' folder does not exist in the current directory: {os.getcwd()}. "
            "Please create the 'tmp/' subfolder manually or set `allow_create = True`.\n"
        )
else:
    print(f"\n\nUsing existing temporary folder: {tmp_folder}\n")

---

Step 2: Initialize the Simulation Box

Use the region class to define the simulation box. Add global parameters such as dimensions, boundary conditions, and lattice details.

from pizza.region import region

# Initialize the simulation box
R = region(
    name="SimulationBox",  # Name of the simulation box
    dimension=3,  # 3D simulation
    boundary=["f", "f", "f"],  # Fixed boundary conditions
    nbeads=3,  # Number of bead types
    width=0.08, height=0.08, depth=0.06,  # Dimensions in meters
    units="si",  # Use SI units
    regionunits="si",  # Define regions in SI units
    lattice_scale=0.001,  # Lattice scale in meters
    lattice_style="sc",  # Simple cubic lattice
    lattice_spacing=0.001,  # Spacing between lattice points
    separationdistance=0.001,  # Minimum separation between points
    mass=1.0  # Default mass
)

---

Step 3: Add Cylindrical Subregions

Define subregions (cylinders) within the simulation box using the cylinder method of the region class.

# Add cylindrical subregions with different bead types
R.cylinder(name="LowerCylinder", dim="z", c1=0, c2=0, radius=0.03, lo=-0.03, hi=-0.01, beadtype=1)
R.cylinder(name="CentralCylinder", dim="z", c1=0, c2=0, radius=0.03, lo=-0.01, hi=0.01, beadtype=2)
R.cylinder(name="UpperCylinder", dim="z", c1=0, c2=0, radius=0.03, lo=0.01, hi=0.03, beadtype=3)

Generate initialization scripts for the region.

# Generate initialization headers for the region
Rheaders = R.pscriptHeaders(what=["init", "lattice", "box"])

---

Step 4: Manage Groups

Use groupobject to define groups of atoms for each bead type and combine them into a collection.

from pizza.group import group, groupobject

# Create group objects for each bead type
g1 = groupobject(beadtype=1, group='lower', mass=2.0)
g2 = groupobject(beadtype=2, group='middle')
g3 = groupobject(beadtype=3, group='upper')

# Combine group objects into a collection
gcollection = g1 + g2 + g3

# Generate a script to assign masses
Mscript = gcollection.mass(default_mass=R.mass)

Evaluate and define relationships between groups.

# Define and evaluate groups
G = group(name="1+2+3", collection=gcollection)
G.evaluate("all", G.lower + G.middle + G.upper)
G.evaluate("external", G.all - G.middle)

# Generate a script to count atoms in each group
Ncontrol = G.count(selection=["all", "lower", "middle", "upper"])

---

Step 5: Preview and Combine Scripts

Preview the region geometry and combine all scripts using pipescript.

# Preview the region geometry
Rpreview = R.pscriptHeaders(what="preview")

# Combine all scripts into a single pipeline
from pizza.script import pipescript

S = Rheaders | R | G | Mscript | Ncontrol | Rpreview

Write the full script to a file.

# Write the combined LAMMPS script to a file
scriptfile = S.write("tmp/example2.txt", verbosity=1, overwrite=True)
print(f"The LAMMPS script is available here:\n{scriptfile}")

---

Step 6: Generate DSCRIPT

Export the combined LAMMPS script to a DSCRIPT format for future reuse.

from pizza.dscript import dscript

# Convert to DSCRIPT
D = S.dscript(verbose=True)
dscriptfile = D.save("tmp/example2.d.txt", overwrite=True)
print(f"The DSCRIPT is available here:\n{dscriptfile}")

---

Step 7: Validate Reversibility

Reload the DSCRIPT file and regenerate the LAMMPS script to ensure consistency.

# Load DSCRIPT and regenerate the LAMMPS script
Dreverse = dscript.load(dscriptfile)
Sreverse = Dreverse.pipescript(verbose=False)

# Output the regenerated script
print("\n\n# Reverse LAMMPS code (from disk)", Sreverse.do(verbose=False...