HT Relax

1. Overview

HT Relax enables high-throughput structural relaxation of multiple structures using machine learning force fields. This module is specifically designed to work with completed HT SQS explorations, creating batch ML relaxation jobs for all generated SQS structures.

The workflow creates individual ML relaxation tasks for each completed SQS structure, allowing efficient parallel processing of large structure sets with consistent relaxation parameters.

For individual ML relaxation of single structures, see ML Relax.

2. Creating HT MLRelax Explorations

HT Relax works by taking completed HT SQS explorations and creating ML relaxation tasks for all generated structures:

from atomict.simulation.ht_relax import create_ht_mlrelax_exploration

# Create HT MLRelax from completed HT SQS exploration
result = create_ht_mlrelax_exploration(
    project_id="project_id",
    name="Al-Ni High-Throughput Relaxation",
    source_ht_sqs_exploration_id="completed_ht_sqs_id",
    model="orb_v3_conservative",
    f_max=0.03
)

ht_mlrelax_id = result.get('id')

2.1 Parameter Details

HT MLRelax requires a source_ht_sqs_exploration_id from a completed HT SQS exploration.

Source HT SQS Exploration

The completed HT SQS exploration that generated the structures to be relaxed:

• Must be in "completed" status
• Contains multiple SQS structures from different concentration permutations
• Each structure becomes an individual ML relaxation task

Relaxation Parameters

• model="orb_v3_conservative" - ML force field model for relaxation
• f_max=0.03 - Force convergence criterion (eV/Å)
• max_steps=500 - Maximum optimization steps (optional)

Available ML Models

3. Working with HT MLRelax Children

HT MLRelax creates individual ML relaxation tasks for each structure from the source HT SQS exploration. These child tasks can be monitored and managed individually.

3.1 Getting Exploration with Children

After creating an HT MLRelax exploration, you can retrieve detailed information including all individual ML relaxation tasks that were created for each SQS structure.

from atomict.simulation.ht_relax import get_ht_mlrelax_exploration

# Get exploration with individual ML relaxation tasks
with_children = get_ht_mlrelax_exploration(ht_mlrelax_id, include_children=True)
individual_tasks = with_children.get('mlrelax_tasks', [])

for i, task in enumerate(individual_tasks):
    print(f"Task {i+1}: {task['name']}")
    print(f"Status: {task.get('status', 'Unknown')}")
    print(f"Model: {task.get('model', 'Unknown')}")

3.2 Monitoring Task Progress

Individual ML relaxation tasks have their own status and can be monitored for completion. This allows you to track progress across all structures in your batch relaxation.

def monitor_progress(exploration_id):
    exploration = get_ht_mlrelax_exploration(exploration_id, include_children=True)
    
    total_tasks = len(exploration.get('mlrelax_tasks', []))
    completed_tasks = sum(1 for task in exploration.get('mlrelax_tasks', []) 
                         if task.get('status') == 3)  # Status 3 = completed
    
    print(f"Progress: {completed_tasks}/{total_tasks} tasks completed")
    return completed_tasks, total_tasks

# Monitor progress
completed, total = monitor_progress(ht_mlrelax_id)

4. Managing HT MLRelax Explorations

4.1 Listing Explorations

from atomict.simulation.ht_relax import list_ht_mlrelax_explorations

# List all HT MLRelax explorations
all_explorations = list_ht_mlrelax_explorations()
print(f"Total explorations: {all_explorations['count']}")

# Filter by project
project_explorations = list_ht_mlrelax_explorations(
    project_id="project_id"
)

# Pagination support
paginated = list_ht_mlrelax_explorations(limit=10, offset=0)

4.2 Getting Exploration Details

from atomict.simulation.ht_relax import get_ht_mlrelax_exploration

# Get basic exploration details
exploration = get_ht_mlrelax_exploration(ht_mlrelax_id)
print(f"Name: {exploration['name']}")
print(f"ML Model: {exploration['model']}")
print(f"F_max: {exploration['f_max']}")
print(f"Status: {exploration['status']}")

# Get exploration with individual ML relaxation tasks
with_children = get_ht_mlrelax_exploration(ht_mlrelax_id, include_children=True)
print(f"Individual tasks: {len(with_children.get('mlrelax_tasks', []))}")

4.3 Updating Explorations

from atomict.simulation.ht_relax import update_ht_mlrelax_exploration

# Update parameters before launching
updated = update_ht_mlrelax_exploration(
    ht_mlrelax_id,
    f_max=0.025,
    max_steps=1000,
    description="Updated with tighter convergence criteria"
)