How-To Guides

How-To Guides#

Step-by-step guides for common tasks and workflows with aiida-atomistic.

Quick Navigation#

🏗️ Creating and Modifying Structures#

Learn the basics of structure creation and manipulation:

  • How-to Guide: Creation and Mutation

  • Topics: Initialization, mutable vs immutable, conversion methods

  • Use cases: Building structures, importing from files

🧲 Magnetic Structures#

Learn how to add magnetic moments and work with magnetic materials:

  • How-to Guide: Working with Magnetic Structures

  • Topics: Collinear magnetism, non-collinear spins, magnetic kinds

  • Use cases: Magnetic materials, spin-polarized calculations

User Guides#

🏗️ Creating and Modifying Structures#

Learn the basics of structure creation and manipulation:

  • How-to Guide: Creation and Mutation

  • Topics: Initialization methods, mutable vs immutable, conversion between formats

  • Use cases: Building structures from scratch, importing from files, modifying existing structures

What you’ll learn:

  • Create structures from dictionaries, ASE, pymatgen

  • Use StructureDataMutable for building and editing

  • Convert between mutable and immutable structures

  • Export to various formats (CIF, MCIF, ASE, pymatgen)

🧲 Working with Magnetic Structures#

Add and manipulate magnetic properties:

  • How-to Guide: Magnetic Structures

  • Topics: Collinear and non-collinear magnetism, magnetic kinds, total magnetization

  • Use cases: Magnetic materials, spin-polarized DFT calculations, magnetic ordering

What you’ll learn:

  • Set collinear magnetic moments

  • Define non-collinear spin orientations

  • Work with magnetic kinds

  • Calculate total magnetization

🏷️ Understanding and Using Kinds#

Master the kinds system for efficient structure representation:

  • How-to Guide: Working with Kinds

  • Topics: Automatic kind generation, tolerance system, kind validation, manual assignment

  • Applications: Storage optimization, plugin compatibility, large structures

What you’ll learn:

  • What kinds are and why they matter

  • Generate kinds automatically with generate_kinds()

  • Control tolerances for property comparison

  • Validate kind consistency

  • Access kind-based structure representations

🎨 Defining Custom Properties#

Store additional structure-related information:

  • How-to Guide: Custom Properties

  • Topics: Using the custom dictionary, when to use extras instead

  • Use cases: Plugin-specific data, experimental metadata, specialized properties

What you’ll learn:

  • Store custom data in structures

  • Difference between custom dict and AiiDA extras

  • Best practices for custom properties

🔍 Querying Structures#

Find and analyze structures in your database:

  • How-to Guide: Querying Structures

  • Topics: Search patterns, property filtering, QueryBuilder usage

  • Tools: AiiDA QueryBuilder integration

What you’ll learn:

  • Query structures by properties

  • Filter by composition, magnetic properties, etc.

  • Efficient database searches

Developer Guides#

🔧 Adding New Properties#

Extend aiida-atomistic with new property types:

  • Developer Guide: Adding Properties

  • Topics: Site vs global properties, computed fields, setters/getters, validation, testing

  • For: Contributors adding features to aiida-atomistic

What you’ll learn:

  • Add new site properties with full integration

  • Add new global properties

  • Implement computed fields for array access

  • Write validators and tests

  • Contribute via fork and pull request

🔌 Migrating Your Plugin#

Update your AiiDA plugin to support aiida-atomistic:

  • Developer Guide: Plugin Migration

  • Topics: Property validation, supported properties, backward compatibility

  • For: Plugin developers migrating from legacy orm.StructureData

What you’ll learn:

  • Access properties via the properties attribute

  • Validate supported properties in CalcJobs

  • Handle unsupported properties gracefully

  • Support both legacy and atomistic structures

  • Real examples from aiida-quantumespresso

Contents