Chatmosp Kmc Simulator

KMC (Kinetic Monte Carlo) simulation engine of the chatMOSP system. Invokes kmc_standalone.py via Wine to run the Windows main.exe engine, executes catalyst surface reaction kinetic simulations, and produces TOF / coverage results. Uses utils/plot_kmc_data.py to generate coverage.png, coverage_steps.png, tof.png, and tof_time.png (4 images total). Triggers: after parameter-builder has built KMC parameters and the user has confirmed via the 5-option prompt, this skill executes the KMC simulation.

Language routing / 语言路由 Detect the user's language from the latest message.

• If the user writes in English, continue with this English file and respond in English.
• If the user writes in Chinese, read SKILL.md in this same directory and respond in Chinese. Always match the response language to the user's input language.

1. Core Responsibilities

1. Check and manage Wine environment (KMC engine dependency)
2. Prepare KMC input files (copy template from MOSP_database + user-specified steps/T/pp)
3. Execute KMC simulation and monitor progress
4. Warn on large step counts (≥ 20M steps)
5. Generate TOF / coverage plots and CSV data
6. Auto-regenerate plots if missing or on user request

2. Prerequisites

• ✅ MSR task completed (if starting from MSR cluster)
• ✅ parameter-builder has built KMC parameters
• ✅ User has confirmed via the 5-option prompt (see parameter-builder)
• ✅ Wine environment installed (check on first run, prompt install if missing)
• ✅ MSR-generated ini.xyz copied to KMC task directory (if applicable)
• ✅ External mosp-for-chatMOSP installed, with kmc_standalone.py, MOSP_database/, and engine/main.exe
• ❌ DO NOT bypass parameter-builder and build KMC parameters manually
• ❌ DO NOT reuse MSR's input.json — KMC must independently prepare complete parameters

3. Wine Environment

The KMC engine is the Windows main.exe, requiring Wine to run.

3.1 Check Wine

bash

which wine64 || which wine

3.2 Install Wine (Ubuntu/Debian)

bash

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install wine64 wine32

3.3 Automatic environment check

• ✅ Wine installed → proceed normally
• ⚠️ Wine missing → prompt install instructions
• ❌ Version incompatible → prompt upgrade

4. Step-Count Warning

When KMC steps ≥ 20M, MUST warn user before execution:

text

⚠️ Calculation Time Warning:
Current KMC steps: {N}, estimated time: ~{estimated_hours} hours.
(Reference: 20M steps ≈ 12 hours, 40M steps ≈ 24+ hours)
Continue with KMC simulation?

Steps	Estimated time
20M	~12 hours
40M	~24 hours or longer
More	Linear growth

Note: Running multiple conditions (e.g., multiple temperatures) requires separate calculations; total time multiplies.

5. Input Contract (Required fields in input.json)

Top-level fields

Field	Type	Description
Element	string	Metal element (Pd, Pt, Au, etc.)
Lattice constant	string	Lattice constant (Å)
Crystal structure	string	Crystal structure (FCC, BCC, HCP)
Temperature	string	Temperature (K)
Pressure	string	Pressure (Pa)
flag_MSR	boolean	MUST be false
flag_KMC	boolean	MUST be true
KMC	object	KMC parameter object

KMC object required fields

Field	Type	Description
nLoop	string	Simulation steps
record_int	string	Recording interval
nspecies	number	Number of species
nproducts	number	Number of products
nevents	number	Number of reaction events
nevents_mob	number	Number of mobility events
s1 / s2	string	Species 1/2 definitions (JSON string)
p1	string	Product 1 definition (JSON string)
e1 ~ e7	string	Reaction events 1~7 (JSON string)
li	array	Lattice interaction matrix

⚠️ CRITICAL: Gas entropy s1.S_gas / s2.S_gas MUST match MSR's Gas1_S / Gas2_S (use the same calculation formula).

6. Directory Structure

KMC task directory must be under MSR directory:

text

mosp-for-chatMOSP/OUTPUT/{msr_task_name}/
└── KMC_{steps}steps/             ← KMC task directory
    ├── input.json                ← outside INPUT/
    ├── ini.xyz                   ← copied from MSR
    ├── coverage.png              ← generated after run
    ├── coverage_steps.png        ← generated after run
    ├── tof.png                   ← generated after run
    ├── tof_time.png              ← generated after run
    ├── INPUT/                    ← should be empty before run
    └── OUTPUT/                   ← populated after run
        ├── rec_cov.data
        ├── rec_event.data
        └── rec_site_spc.data

⚠️ IMPORTANT:

• ini.xyz and input.json MUST be outside INPUT/ (kmc_standalone.py clears INPUT/OUTPUT)
• Ensure INPUT/ and OUTPUT/ are empty before running

7. Execution Steps

Step 1: Create KMC task directory

bash

mkdir -p OUTPUT/Pd_CO9_O18_473K_101325Pa_R50/KMC_{steps}steps/INPUT
mkdir -p OUTPUT/Pd_CO9_O18_473K_101325Pa_R50/KMC_{steps}steps/OUTPUT

Step 2: Copy structure file

bash

cp OUTPUT/{msr_task_name}/ini.xyz OUTPUT/{msr_task_name}/KMC_{steps}steps/ini.xyz

Step 3: Prepare input.json

bash

# Copy template from MOSP_database (do not create manually)
cp mosp-for-chatMOSP/MOSP_database/{metal}-{reaction}.json \
   OUTPUT/{msr_task_name}/KMC_{steps}steps/input.json

# Adjust fields:
# - nLoop: user-specified steps
# - T: user-specified temperature
# - gas_pp: user-specified partial pressures
# - record_int: recording interval
# - s1.S_gas / s2.S_gas: recalculated using parameter-builder §7.1 formula

Step 4: Show parameters for user confirmation

Use parameter-builder §KMC parameter display format (5 options).

Step 5: Check Wine + step warning

• Check Wine environment
• Warn when steps ≥ 20M

Step 6: Execute KMC

bash

python3 {mosp_root}/kmc_standalone.py \
  --xyz OUTPUT/{task_dir}/ini.xyz \
  --json OUTPUT/{task_dir}/input.json \
  --out-dir {task_dir}

{mosp_root} is normally $HOME/.openclaw/workspace/mosp-for-chatMOSP or $OPENCLAW_WORKSPACE/mosp-for-chatMOSP. Confirm that this directory exists before running.

Note: pass just the task directory name to --out-dir (e.g. {msr_task_name}/KMC_{steps}steps). The script automatically places it under OUTPUT/; even if an OUTPUT/ prefix is accidentally included it is de-duplicated, so no OUTPUT/OUTPUT/ nesting is produced.

8. Output Files

File	Location	Description
coverage.png	KMC task dir	Coverage vs Time
coverage_steps.png	KMC task dir	Coverage vs Steps
tof.png	KMC task dir	TOF vs Time
tof_time.png	KMC task dir	TOF vs Steps
coverage.csv	OUTPUT/	Coverage data
tof.csv	OUTPUT/	TOF data
site_tof.csv	OUTPUT/	Site TOF data
rec_cov.data	OUTPUT/	Coverage records (KMC engine raw output)
rec_event.data	OUTPUT/	Event records
rec_site_spc.data	OUTPUT/	Site-species records

8.1 Sending Images to User (Feishu)

⚠️ One image per call: Feishu message tool only supports 1 image per attachment. Sending more than one will silently drop the extras. After KMC completes, you MUST send the 4 images one at a time with numbered labels.

Send order and labels:

1. Image 1/4: Coverage vs Time — coverage.png
2. Image 2/4: Coverage vs Steps — coverage_steps.png
3. Image 3/4: TOF vs Time — tof.png
4. Image 4/4: TOF vs Steps — tof_time.png

Example per message:

text

message(action=send, message="Image 1/4: Coverage vs Time",
         attachments=[{filePath:"...coverage.png", type:"image"}])

9. Output Check & Auto-Regenerate

After KMC completes (especially when user asks "is the task done?"), MUST check and regenerate plots if needed:

bash

KMC_TASK_DIR="KMC task directory"
KMC_OUTPUT="$KMC_TASK_DIR/OUTPUT"

# 1. Check data files
if [ ! -f "$KMC_OUTPUT/rec_cov.data" ] || \
   [ ! -f "$KMC_OUTPUT/rec_event.data" ] || \
   [ ! -f "$KMC_OUTPUT/rec_site_spc.data" ]; then
  echo "❌ Data files missing, KMC may not have completed"
  exit 1
fi

# 2. Check step-count consistency
EXPECTED=$(grep -E "^[0-9]+\s+! Num of steps" "$KMC_TASK_DIR/INPUT/input.txt" | awk '{print $1}')
ACTUAL=$(tail -n 1 "$KMC_OUTPUT/rec_event.data" | awk '{print $2}')

if [ "$EXPECTED" != "$ACTUAL" ]; then
  echo "❌ Expected $EXPECTED steps, got $ACTUAL, KMC did not complete"
  exit 1
fi

# 3. Check plots (4 images), regenerate if missing
if [ -f "$KMC_TASK_DIR/coverage.png" ] && \
   [ -f "$KMC_TASK_DIR/coverage_steps.png" ] && \
   [ -f "$KMC_TASK_DIR/tof.png" ] && \
   [ -f "$KMC_TASK_DIR/tof_time.png" ]; then
  echo "✅ Plots already exist"
else
  python3 ../../utils/plot_kmc_data.py "$KMC_OUTPUT"
  echo "✅ Plots regenerated"
fi

Plotting script: mosp-for-chatMOSP/utils/plot_kmc_data.py

10. Error Handling

Error	Action
Step-count mismatch	Check KMC log; may not have finished
Data files missing	KMC did not complete; check run.log
Lattice constant missing	Copy complete template from MOSP_database; do not create manually
INPUT/OUTPUT dir missing	Create them in Step 1
ini.xyz missing	Copy from MSR task directory
Wine missing	Prompt install instructions
KMC segfault	Wine version incompatible; prompt upgrade

11. Cross-Skill Handoff

• MSR → KMC: After MSR completes, ini.xyz is produced. This skill independently fetches complete KMC parameters from MOSP_database. Do NOT reuse MSR's input.json.
• Parameter modification: If user changes temperature, parameter-builder MUST recalculate gas entropy per §7.5.
• Long-task query: When user asks "is the task done?", run §9 check script, regenerate plots if needed.

12. Dependencies

• mosp-for-chatMOSP — KMC engine (cloned, includes main.exe)
• chatmosp-parameter-builder — parameter building and gas entropy
• chatmosp-file-organizer — directory creation
• chatmosp-input-coordinator — task entry point
• Wine — required for Windows main.exe

13. File Structure

text

chatmosp-kmc-simulator/
├── SKILL.md       # Chinese reference
└── SKILL_cn.md    # This file (English)

14. Example

text

User: Run KMC simulation for Pt CO oxidation at 850K, 150Pa, 20M steps

System: [Recognize as KMC → parameter-builder searches params →
        Show 5-option confirmation → User confirms → Check Wine installed →
        ⚠️ 20M steps ≈ 12 hours, warn user → User confirms again →
        Prepare input.json → Invoke kmc_standalone.py → Monitor progress →
        Check output → Generate 4 images → Send one-by-one → Display results]

ChatMOSP Companion Skills

This skill is part of the ChatMOSP skill set. For complete functionality, install the companion ChatMOSP skills from ClawHub when they are missing:

• chatmosp-input-coordinator
• chatmosp-parameter-builder
• chatmosp-msr-generator
• chatmosp-kmc-simulator
• chatmosp-literature-search
• chatmosp-file-organizer

If a required companion skill is unavailable, ask the user to install the missing ChatMOSP skill from ClawHub before continuing. Use the GitHub repository only as a fallback.