🍕 Pizza3 Release 1.0 ‐ Overview

Welcome to the Pizza3 Release 1.0 overview! This release marks a significant milestone, introducing a suite of new functionalities and enhancements that elevate your simulation workflows. Explore the scope, features, and detailed examples that make Pizza3 1.0 a powerful tool for your projects.

---

🔍 Scope and Motivation

🏗️ Release 1.0 consolidates several new functionalities and capabilities introduced in beta versions. Notably, dynamic scripting (pizza.dscript) and forcefields (pizza.dforcefield) are now standard features. Here's why:

• Flexibility & Power: Enhanced flexibility with dynamic scripting allows for more adaptable simulations.
• LLM Integration: Leverage Large Language Models like Chat-GPT for improved coding assistance. Remember, Chat-GPT excels in understanding Python better than LAMMPS!
• Multiscale & Multiphysics Modeling: The DSCRIPT language bridges the gap by offering abstraction layers essential for complex simulations.
• Seamless Translation: Automatically convert LAMMPS examples into DSCRIPT without loss, showcased in 📁 pizza.dscript.examples.

---

🔗 Click to Expand Links

---

📚 Online Documentation
🔖 Release Page

📁 Documentation & Release Pages: Automatically updated in 📁 docs/ with the tools available in 📁 utils/.

📁 Core Library Examples: Located in 📁 pizza/ and reported automatically in 📖 Usage Examples.

📁 Post Tools Examples: Located in 📁 post/.

📁 DSCRIPT examples Located in 📁 pizza.dscript.examples/.

---

📜 Click to Expand Changelog

🌟 New Example

• example2bis.py: Showcases new features with a focus on reliability, ensuring full reversibility between formats and representations.

🌟 Tooling Enhancements

• Comprehensive tools (utils/, available in both Bash and Python) to regenerate project documentation and releases seamlessly.

🌟 Improved DSCRIPT Parser

• Supports single-line and multi-line instruction blocks.
• Square brackets ([ ]) are now optional for single-line blocks.

🌟 Unified Script Handling

• Combine SCRIPT, PIPESCRIPT, DSCRIPT, SCRIPTOBJECT, and their collections using operators like | (pipe) and + (addition).
• Conversions prioritize PIPESCRIPT instances, serving as the lingua franca of Pizza3.

🌟 Dynamic Forcefield Management

• DFORCEFIELD class now supports all surrogate methods of FORCEFIELD, enabling accurate SCRIPTOBJECT generation.
• Save & Load: DFORCEFIELD objects can be saved and loaded as plain text files (no Python required), facilitating reusable forcefield definitions.
• Derivation: Forcefields can be derived from parent FORCEFIELD instances defined statically.

🌟 Enhanced Script Conversions

• Convert complex PIPESCRIPT instances (including those with forcefields) into modifiable DSCRIPT instances without information loss.
• Save, Load & Recombine: DSCRIPT instances can be seamlessly saved, loaded, and recombined with PIPESCRIPT.
• Optimization: pizza.dscript.save() optimizes variable definitions by distinguishing between GLOBAL and LOCAL variables.

🌟 DSCRIPT Interpreter

• DSCRIPT instances now include a standalone static interpreter (pizza.dscript.do()), eliminating the need for conversion to a PIPESCRIPT instance.

🌟 Advanced Debugging and Design

• list_values() Method: Track values across pipes (static, global, local) and chained DSCRIPT instances for debugging and advanced script design.
• search() Method: Retrieve any value from DSCRIPT instances using a primary key (e.g., beadtype), aiding in reloading and updating DSCRIPT files.

---

🔬 Follow-up Example: example2bis.py - Introducing Physics via a Forcefield

This example builds upon example2 by integrating physical properties into the simulation through forcefields.

Overview: Demonstrates the creation and management of forcefield objects, their assignment to specific regions, and the generation of scripts with physical interactions.

---

🎯 Objective

Integrate physical parameters into the simulation using forcefields, enhancing the functionality of the previous example. Forcefields define material properties and interactions for particles within the simulation.

---

🌟 What You Will Learn

1. Forcefield Initialization and Configuration:

   • Create a default forcefield with physical properties.
   • Define forcefield parameters programmatically or using DSCRIPT syntax.
   • Save, load, and reuse forcefields dynamically.

2. Specialized Forcefields for Regions:

   • Derive specialized forcefields for specific regions using a copy method.
   • Modify parameters (e.g., density, elastic modulus) for each subregion.

3. Particle Interaction Management:

   • Assign forcefields to atom groups for interactions.
   • Manage inter-particle interactions using group-based scripts.

4. Script Update and Integration:

   • Merge the new forcefields with the previous script.
   • Update the simulation workflow programmatically.

5. Advanced Analysis and Debugging:

   • Analyze occurrences of variables and parameters in scripts.
   • Generate reports for debugging and visualization.

---

🧩 Structure of the Script

1. 📥 Loading the Previous Script

• Load the DSCRIPT file generated in example2.
• Extract and analyze key variables such as beadtype and region arguments.

2. 🛠️ Defining the Default Forcefield

• Create a base forcefield using parameterforcefield and dforcefield.
• Assign common physical properties (e.g., density, elastic modulus).
• Save and reload the forcefield to demonstrate file-based management.

3. 🧬 Specialized Forcefields for Subregions

• Derive forcefields for each subregion (LowerCylinder, CentralCylinder, UpperCylinder).
• Modify physical properties for each region to simulate different materials.

4. 🔗 Assigning Forcefields to Groups

• Create group scripts for particles in each region using the specialized forcefields.
• Combine these group scripts into a cohesive collection.

5. 🔄 Updating the Simulation Script

• Integrate the new forcefields into the original script.
• Use slicing and combination operations with pipescript to update the workflow.

6. 💾 Generating and Saving the Updated Scripts

• Generate a new LAMMPS script (example2bis.txt) with physical properties.
• Convert the updated script to DSCRIPT format for future reuse.
• Save the DSCRIPT file for reverse engineering.

7. 🔍 Verifying Reversibility

• Reload the updated DSCRIPT file.
• Regenerate the LAMMPS script to validate consistency.
• Generate variable reports for debugging.

---

🛠️ Key Components and Tools

🔧 Forcefield Management

• Base Forcefield: The default set of parameters common across regions.
• Specialized Forcefields: Region-specific forcefields derived from the base forcefield.

📚 Classes and Methods

Class/Module	Functionality
parameterforcefield	Defines physical parameters for a forcefield.
dforcefield	Manages dynamic forcefields, including parameter inheritance and file I/O.
tlsph	Specifies the forcefield type (e.g., Total Lagrangian Smoothed Particle Hydrodynamics).
dscript	Converts LAMMPS scripts to DSCRIPT format for modularity and reuse.

🚀 Advanced Features

• Variable Substitution: Dynamic evaluation of parameters using ${variable_name} syntax.
• Scripting Flexibility: Combine, update, and slice scripts programmatically with pipescript.
• Debugging Tools: Generate reports and analyze occurrences of variables and parameters.

---

🐍 Execution Steps and Python Code

🥇 Step 1: Load the Previous Script

Load the DSCRIPT file generated in example2 and extract key information for reuse.

from pizza.dscript import dscript

# Load the previous DSCRIPT file
dscriptfilename = "tmp/example2.d.txt"
previoussteps = dscript.load(dscriptfilename)

# Extract beadtype and region arguments
beadtype = previoussteps.search("ID", previoussteps.list_values("ID"), "beadtype")
region_args = previoussteps.list_values('args', details=True).get_raw_data()

---

🥈 Step 2: Define the Default Forcefield

Create a base forcefield with common physical properties and save it for reuse.

from pizza.forcefield import parameterforcefield, tlsph
from pizza.dforcefield import dforcefield

# Define the default forcefield
FFbase_parameters = parameterforcefield(
    base_class=tlsph,
    rho=1050, c0=10.0,
    E="50*${c0}^2*${rho}",
    nu=0.3, q1=1.0, q2=0.0, Hg=10.0,
    Cp=1.0, sigma_yield="0.1*${E}", hardening=0,
    contact_scale=1.5, contact_stiffness="2.5*${c0}^2*${rho}"
)
FFbase = dforcefield(userid="FFbase", **FFbase_parameters)

# Save and reload the forcefield
FFbase.save('FFbase.default.txt', foldername="./tmp", overwrite=True, verbose=False)
FFbase = dforcefield.load('FFbase.default.txt', foldername="./tmp")

---

🥉 Step 3: Define Specialized Forcefields

Derive forcefields for specific subregions and adjust their properties.

# Define specialized forcefields for each region
FFlower = FFbase.copy(beadtype=beadtype["LowerCylinder"], userid="LowerCylinder", E="2*"+FFbase.parameters.E, rho=1050)
FFcentral = FFbase.copy(beadtype=beadtype["CentralCylinder"], userid="CentralCylinder", E="0.5*"+FFbase.parameters.E, rho=1000)
FFupper = FFbase.copy(beadtype=beadtype["UpperCylinder"], userid="UpperCylinder", E="10*"+FFbase.parameters.E, rho=1300, nu=0.1)

---

🔗 Step 4: Assign Forcefields to Groups

Create group scripts and combine them into a cohesive collection.

blower = FFlower.scriptobject(name="lowerAtoms", group="lowerAtoms")
bcentral = FFcentral.scriptobject(name="centralAtoms", group="centralAtoms")
bupper = FFupper.scriptobject(name="upperAtoms", group="upperAtoms")
bcollection = blower + bcentral + bupper

---

🔄 Step 5: Update the Simulation Script

Merge the new forcefields with the original script using slicing and combination operations.

# Combine the previous script with the new forcefields
updatedScript = previoussteps[:-1] | bcollection | previoussteps[-1:]

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

---

💾 Step 6: Save the Updated Script

Convert the updated script to DSCRIPT format and save it.

DupdatedScript = updatedScript.dscript(verbose=True)
DupdatedScriptFile = DupdatedScript.save("tmp/example2bis.d.txt", overwrite=True)
print(f"The updated DSCRIPT is available here:\n{DupdatedScriptFile}")

---

🔍 Step 7: Verify Reversibility

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

Drev2bis = dscript.load(DupdatedScriptFile)
Srev2bis = Drev2bis.pipescript(verbose=False)

# Save the reversed script
revUpdatedScriptfile = Srev2bis.write("tmp/example2bis.rev.txt", verbosity=0, overwrite=True)
print(f"The updated and reversed LAMMPS script is available here:\n{revUpdatedScriptfile}")

---

🌟 Key Outputs

1. 📄 Updated LAMMPS Script:

   • File: tmp/example2bis.txt
   • Description: Includes physical parameters and forcefield definitions.

2. 📄 Updated DSCRIPT File:

   • File: tmp/example2bis.d.txt
   • Description: Modular representation of the updated workflow.

3. 📄 Reversed LAMMPS Script:

   • File: tmp/example2bis.rev.txt
   • Description: Validated for consistency with the original workflow.

4. 📊 Debugging Reports:

   • Description: Reports for variables and parameters in the script (e.g., args, move).

---

🚀 Conclusion

This example illustrates the seamless integration of physical properties into your simulation workflow using Pizza3. By introducing forcefields, customizing region parameters, and dynamically updating scripts, Pizza3 1.0 offers:

• Flexibility: Easily adapt simulations to complex, real-world scenarios.
• Reusability: Modular scripts and forcefields ensure components can be reused across projects.
• Debuggability: Advanced tools and methods simplify the debugging and optimization process.
• Extensibility: The framework is designed to grow with your simulation needs, supporting multiscale and multiphysics modeling.

Embrace the power of Pizza3 1.0 to create more realistic and flexible simulations with ease!

---

📢 Get Involved

Have questions, suggestions, or need support? Visit our GitHub Repository to contribute, report issues, or collaborate with the community.

---

📄 License

Pizza3 is open-source software licensed under the MIT License.

---

Happy Simulating! 🍕