HT SQS

1. Overview

HT SQS enables high-throughput generation of special quasi-random structures with multiple concentration permutations. This is ideal for systematic alloy composition screening where you want to generate SQS structures for multiple concentration ratios in a single workflow.

This should be followed up with HT Relax as the generated SQS structures are unrelaxed and need geometry optimization before property calculations or further analysis.

2. Creating HT SQS Explorations

Unlike normal SQS, you need to supply target concentrations as dictionaries and generate multiple concentration permutations:

from atomict.simulation.ht_sqs import create_ht_sqs_exploration

# Define specific compositions to generate SQS for
generated_permutations = [
    {"Al": 0.7, "Ni": 0.3},  # 70% Al, 30% Ni
    {"Al": 0.5, "Ni": 0.5},  # 50% Al, 50% Ni  
    {"Al": 0.8, "Ni": 0.2}   # 80% Al, 20% Ni
]

result = create_ht_sqs_exploration(
    project_id="project_id",
    name="Advanced Al-Ni HT SQS",
    generated_permutations=generated_permutations,
    structure_id="structure_id",
    structure_type="userupload",
    max_size=64,
    cluster_cutoffs=[6.0, 4.0],
    structures_per_permutation=5,
    description="description"
)

exploration_id = result.get("id")

2.1 Parameter Details

HT SQS requires generated_permutations to define the compositions for SQS creation.

Generated Permutations

The compositions that actually get turned into individual SQS simulations. Each permutation creates a separate child SQS exploration:

• {"Al": 0.8, "Ni": 0.2} - Creates SQS simulation with 80% Al, 20% Ni
• {"Al": 0.5, "Ni": 0.5} - Creates SQS simulation with 50% Al, 50% Ni

Supercell Parameters

• max_size=64 - Maximum number of atoms in generated supercell
• cluster_cutoffs=[6.0, 4.0] - Distances (Å) for pair and triplet cluster correlations
• structures_per_permutation=5 - Number of SQS structures to generate per composition

3. Working with HT SQS Children

HT SQS creates junction records that link to individual SQS explorations for each concentration permutation. These child SQS explorations can be launched and managed like normal SQS simulations.

3.1 Listing Children by Parent

After creating an HT SQS exploration, you can list all the child SQS explorations that were generated for each concentration permutation. This allows you to see which individual SQS simulations were created and monitor their progress.

from atomict.simulation.ht_sqs import list_ht_sqs_children

# List all children for a parent exploration
children = list_ht_sqs_children(parent_exploration_id=exploration_id)

for child in children['results']:
    print(f"Child ID: {child['id']}")
    print(f"SQS Exploration: {child['sqs_exploration']['name']}")
    print(f"Target composition: {child['sqs_exploration']['target_concentrations']}")

3.2 Getting Child Details

Once you've identified child SQS explorations of interest, you can retrieve detailed information about individual children including their linked SQS exploration data. This is useful for accessing the actual SQS structures and monitoring completion status of specific concentration permutations.

from atomict.simulation.ht_sqs import get_ht_sqs_child

# Get specific child details with linked SQS exploration
if children['results']:
    child_id = children['results'][0]['id']
    child_detail = get_ht_sqs_child(child_id)
    
    # Access linked SQS exploration
    sqs_exploration = child_detail['sqs_exploration']
    print(f"SQS Name: {sqs_exploration['name']}")
    print(f"SQS Status: {sqs_exploration['status']}")
    print(f"Structure count: {sqs_exploration.get('structure_count', 'N/A')}")

4. Managing HT SQS Explorations

4.1 Listing Explorations

from atomict.simulation.ht_sqs import list_ht_sqs_explorations

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

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

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

4.2 Getting Exploration Details

from atomict.simulation.ht_sqs import get_ht_sqs_exploration

# Get basic exploration details
exploration = get_ht_sqs_exploration(exploration_id)
print(f"Name: {exploration['name']}")
print(f"Status: {exploration['status']}")
print(f"Target concentrations: {len(exploration['target_concentrations'])}")

# Get exploration with child SQS instances
with_children = get_ht_sqs_exploration(exploration_id, include_children=True)
print(f"Child SQS explorations: {len(with_children.get('children', []))}")