Crystal Structure Analysis (CSA)

Getting Started

  • Getting Started
    • Overview
    • What You’ll Learn
    • Prerequisites
    • Quick Start Path (55 minutes)
    • Detailed Learning Path
    • Choose Your Starting Point
    • What You’ll Accomplish
    • Common Research Applications
    • Essential Next Steps
    • Getting Help
    • Ready to Begin?
      • Installation
        • System Requirements
        • Step 1: Install Python and Prerequisites
        • Step 2: Install CCDC Software
        • Step 3: Install CSA
        • Step 4: Configure CSA
        • Step 5: GPU Setup (Optional but Recommended)
        • Step 6: Verify Installation
        • Troubleshooting
        • Next Steps
      • Quickstart Guide
        • Prerequisites
        • The Five-Stage CSA Pipeline
        • Step 1: Create Your Configuration
        • Step 2: Run Your First Analysis
        • Step 3: Explore Your Results
        • Step 4: Your First Analysis
        • Step 5: Understanding Your Results
        • Common Issues and Solutions
        • Next Steps: Expanding Your Analysis
        • Congratulations!
        • Ready for More?
      • Configuration
        • Quick Start Configuration
        • Essential Parameters
        • Performance Settings
        • Common Configurations
        • Creating Your Configuration
        • Validation and Testing
        • Common Beginner Mistakes
        • Getting Help
        • Next Steps
        • See Also
  • Installation
    • System Requirements
    • Step 1: Install Python and Prerequisites
      • Python 3.9 Installation
    • Step 2: Install CCDC Software
      • CSD Software Suite
    • Step 3: Install CSA
      • Download CSA
      • Create Virtual Environment
      • Install Dependencies
    • Step 4: Configure CSA
      • Set Environment Variables
    • Step 5: GPU Setup (Optional but Recommended)
      • CUDA Installation
    • Step 6: Verify Installation
      • Quick Verification Script
      • Expected Output
    • Troubleshooting
      • Common Installation Issues
      • Getting Additional Help
    • Next Steps
  • Quickstart Guide
    • Prerequisites
    • The Five-Stage CSA Pipeline
    • Step 1: Create Your Configuration
      • Create a Simple Configuration
      • Configuration Explained
    • Step 2: Run Your First Analysis
      • Execute the Pipeline
      • Monitor Progress
      • Understanding the Stages
    • Step 3: Explore Your Results
      • Check Generated Files
      • Quick Data Overview
    • Step 4: Your First Analysis
      • Crystal Property Analysis
      • Fragment Shape Analysis
    • Step 5: Understanding Your Results
      • What You’ve Created
      • Key Insights from Your Data
    • Common Issues and Solutions
      • “No structures found”
      • “Out of memory” errors
      • “Very slow processing”
    • Next Steps: Expanding Your Analysis
      • Try Different Chemical Systems
      • Explore Advanced Features
      • Scale Up Your Research
    • Congratulations!
    • Ready for More?
  • Configuration
    • Quick Start Configuration
      • Minimal Configuration
      • Complete Basic Configuration
    • Essential Parameters
      • Required Settings
      • Pipeline Control
      • Basic Filters
      • Element Species Filtering
    • Performance Settings
      • Batch Sizes
    • Common Configurations
      • Small Organic Molecules
      • Drug-Like Molecules
    • Creating Your Configuration
      • Step-by-Step Process
    • Validation and Testing
      • Check Your JSON
    • Common Beginner Mistakes
      • JSON Syntax Errors
      • Configuration Issues
    • Getting Help
      • When Things Go Wrong
    • Next Steps
    • See Also

User Guide

  • User Guide
    • Overview
    • Core Concepts
      • Essential Concepts
      • Key Features at a Glance
      • Common Workflows
    • Understanding CSA’s Approach
      • Scientific Foundation
      • Technical Architecture
    • User Guide Sections
      • Core Workflows
        • Pipeline Overview
        • Data Model
        • Configuration
        • Basic Analysis
      • Advanced Techniques
      • Data Management
      • Performance Optimization
    • Getting the Most from CSA
      • Best Practices
      • Performance Tips
      • Common Pitfalls
    • Next Steps

Tutorials

  • Tutorials
    • Getting Started Tutorials
    • Domain-Specific Tutorials
    • Advanced Analysis Tutorials
    • Specialized Workflows
    • Tutorial Structure
    • Quick Start Recommendations
    • Tutorial Downloads
    • Tutorial Support
    • Contributing Tutorials
    • Learning Paths
    • Advanced Topics
    • Feedback and Improvement
    • Getting Help
      • Your First Analysis
        • Learning Objectives
        • Prerequisites
        • Tutorial Overview
        • Understanding the CSA Pipeline
        • Step 1: Setup and Configuration
        • Step 2: Pipeline Execution
        • Step 3: Exploring the Results
      • Congratulations!
        • What You’ve Accomplished
        • Next Steps: Analyzing Your Data

Examples

  • Examples
    • Quick Start Examples
    • Data Access Examples
    • Analysis Examples
    • Visualization Examples
    • Integration Examples
    • Performance Examples
    • Example Categories
      • Basic Data Operations
      • Advanced Workflows
    • Configuration Templates
      • Common Configuration Patterns
    • Utility Functions
      • Commonly Used Helper Functions
    • Interactive Examples
      • Jupyter Notebook Examples
      • Command Line Examples
    • Troubleshooting Examples
      • Common Issues and Solutions
    • Example Downloads
    • Browse Examples by Category

API Reference

  • API Reference
    • crystal_analyzer module
      • Dependencies
      • CrystalAnalyzer
        • CrystalAnalyzer.extraction_config
        • CrystalAnalyzer.csd_ops
        • CrystalAnalyzer.extractor
        • CrystalAnalyzer.data_dir
        • CrystalAnalyzer.__init__()
        • CrystalAnalyzer.extract_data()
      • CrystalAnalyzer Class
        • CrystalAnalyzer
      • Methods
        • extract_data()
        • Private Methods
        • Private Attributes
      • Error Handling
      • Configuration Dependencies
      • Performance Considerations
      • See Also
    • csa_config module
      • ExtractionConfig
        • ExtractionConfig.from_json()
        • ExtractionConfig.data_directory
        • ExtractionConfig.data_prefix
        • ExtractionConfig.actions
        • ExtractionConfig.filters
        • ExtractionConfig.extraction_batch_size
        • ExtractionConfig.post_extraction_batch_size
        • ExtractionConfig.from_json()
        • ExtractionConfig.__init__()
      • load_config()
      • Configuration Management for CSA Pipeline
      • ExtractionConfig Class
        • ExtractionConfig
      • Configuration Loading Functions
        • load_config()
      • Configuration Validation
      • Examples
      • See Also
    • csa_main module
      • Dependencies
      • setup_logging()
      • parse_args()
      • run_extraction()
      • main()
      • Command-Line Interface for CSA Pipeline
      • Main Functions
        • main()
        • run_extraction()
      • Configuration and Logging
        • setup_logging()
        • parse_args()
      • Command-Line Usage
      • Integration Examples
      • Performance Considerations
      • See Also
    • csd_operations module
      • Dependencies
      • SimilaritySettings
        • SimilaritySettings.distance_tolerance
        • SimilaritySettings.angle_tolerance
        • SimilaritySettings.ignore_bond_types
        • SimilaritySettings.ignore_hydrogen_counts
        • SimilaritySettings.ignore_hydrogen_positions
        • SimilaritySettings.packing_shell_size
        • SimilaritySettings.ignore_spacegroup
        • SimilaritySettings.normalise_unit_cell
        • SimilaritySettings.__init__()
      • CSDOperations
        • CSDOperations.data_directory
        • CSDOperations.data_prefix
        • CSDOperations.reader
        • CSDOperations.similarity_engine
        • CSDOperations.__init__()
        • CSDOperations.get_refcode_families_df()
        • CSDOperations.save_refcode_families_csv()
        • CSDOperations.filter_families_by_size()
        • CSDOperations.cluster_families()
        • CSDOperations.get_unique_structures()
      • Cambridge Structural Database Operations
      • SimilaritySettings Class
        • SimilaritySettings
      • CSDOperations Class
        • CSDOperations
      • Family Extraction Methods
        • CSDOperations.get_refcode_families_df()
        • CSDOperations.save_refcode_families_csv()
        • CSDOperations.filter_families_by_size()
      • Clustering Methods
        • CSDOperations.cluster_families()
        • CSDOperations._check_structure()
      • Representative Selection Methods
        • CSDOperations.get_unique_structures()
        • CSDOperations._save_unique_structures()
      • Utility Functions
        • _process_single_family()
        • _representative_for_cluster()
      • See Also
    • structure_data_extractor module
      • Dependencies
      • StructureDataExtractor
        • StructureDataExtractor.hdf5_path
        • StructureDataExtractor.filters
        • StructureDataExtractor.batch_size
        • StructureDataExtractor.reader
        • StructureDataExtractor.__init__()
        • StructureDataExtractor.run()
      • Raw Structure Data Extraction Pipeline
      • StructureDataExtractor Class
        • StructureDataExtractor
      • Data Extraction Functions
        • _extract_one()
      • HDF5 Data Organization
      • Usage Examples
      • Data Access Patterns
      • Performance Considerations
      • See Also
    • structure_post_extraction_processor module
      • Dependencies
      • CrystalParams
        • CrystalParams.cell_lengths
        • CrystalParams.cell_angles
        • CrystalParams.cell_lengths
        • CrystalParams.cell_angles
        • CrystalParams.count()
        • CrystalParams.index()
      • AtomParams
        • AtomParams.labels
        • AtomParams.symbols
        • AtomParams.coords
        • AtomParams.frac_coords
        • AtomParams.mask
        • AtomParams.weights
        • AtomParams.charges
        • AtomParams.labels
        • AtomParams.symbols
        • AtomParams.coords
        • AtomParams.frac_coords
        • AtomParams.mask
        • AtomParams.weights
        • AtomParams.charges
        • AtomParams.count()
        • AtomParams.index()
      • BondParams
        • BondParams.atom1_idx
        • BondParams.atom2_idx
        • BondParams.bond_type
        • BondParams.is_rotatable_raw
        • BondParams.is_cyclic
        • BondParams.mask
        • BondParams.atom1_idx
        • BondParams.atom2_idx
        • BondParams.bond_type
        • BondParams.is_rotatable_raw
        • BondParams.is_cyclic
        • BondParams.mask
        • BondParams.count()
        • BondParams.index()
      • InterCCParams
        • InterCCParams.central_atom
        • InterCCParams.contact_atom
        • InterCCParams.central_atom_idx
        • InterCCParams.contact_atom_idx
        • InterCCParams.central_atom_frac_coords
        • InterCCParams.contact_atom_frac_coords
        • InterCCParams.lengths
        • InterCCParams.strengths
        • InterCCParams.in_los
        • InterCCParams.symmetry_A
        • InterCCParams.symmetry_T
        • InterCCParams.symmetry_A_inv
        • InterCCParams.symmetry_T_inv
        • InterCCParams.central_atom
        • InterCCParams.contact_atom
        • InterCCParams.central_atom_idx
        • InterCCParams.contact_atom_idx
        • InterCCParams.central_atom_frac_coords
        • InterCCParams.contact_atom_frac_coords
        • InterCCParams.lengths
        • InterCCParams.strengths
        • InterCCParams.in_los
        • InterCCParams.symmetry_A
        • InterCCParams.symmetry_T
        • InterCCParams.symmetry_A_inv
        • InterCCParams.symmetry_T_inv
        • InterCCParams.count()
        • InterCCParams.index()
      • InterHBParams
        • InterHBParams.central_atom
        • InterHBParams.hydrogen_atom
        • InterHBParams.contact_atom
        • InterHBParams.central_atom_idx
        • InterHBParams.hydrogen_atom_idx
        • InterHBParams.contact_atom_idx
        • InterHBParams.central_atom_frac_coords
        • InterHBParams.hydrogen_atom_frac_coords
        • InterHBParams.contact_atom_frac_coords
        • InterHBParams.lengths
        • InterHBParams.angles
        • InterHBParams.in_los
        • InterHBParams.symmetry_A
        • InterHBParams.symmetry_T
        • InterHBParams.symmetry_A_inv
        • InterHBParams.symmetry_T_inv
        • InterHBParams.central_atom
        • InterHBParams.hydrogen_atom
        • InterHBParams.contact_atom
        • InterHBParams.central_atom_idx
        • InterHBParams.hydrogen_atom_idx
        • InterHBParams.contact_atom_idx
        • InterHBParams.central_atom_frac_coords
        • InterHBParams.hydrogen_atom_frac_coords
        • InterHBParams.contact_atom_frac_coords
        • InterHBParams.lengths
        • InterHBParams.angles
        • InterHBParams.in_los
        • InterHBParams.symmetry_A
        • InterHBParams.symmetry_T
        • InterHBParams.symmetry_A_inv
        • InterHBParams.symmetry_T_inv
        • InterHBParams.count()
        • InterHBParams.index()
      • StructurePostExtractionProcessor
        • StructurePostExtractionProcessor.__init__()
        • StructurePostExtractionProcessor.run()
      • Advanced Feature Engineering Pipeline
      • Data Structure Classes
        • CrystalParams
        • AtomParams
        • BondParams
      • StructurePostExtractionProcessor Class
        • StructurePostExtractionProcessor
      • Fragment Analysis Methods
        • StructurePostExtractionProcessor._compute_rigid_fragments()
      • Geometric Computation Methods
        • StructurePostExtractionProcessor._compute_fragment_com_centroid()
      • Contact Analysis Methods
        • StructurePostExtractionProcessor._expand_inter_contacts()
        • StructurePostExtractionProcessor._flag_hbond_contacts()
        • StructurePostExtractionProcessor._identify_contact_fragments()
      • Advanced Feature Computation
        • StructurePostExtractionProcessor._compute_contact_com_vectors()
      • Data Writing and I/O Methods
      • Usage Examples
      • Performance Optimization
      • See Also
    • geometry_utils module
      • Dependencies
      • compute_distances_to_crystallographic_planes_frac_batch()
      • compute_angles_between_bonds_and_crystallographic_planes_frac_batch()
      • compute_atom_vectors_to_point_batch()
      • compute_bond_rotatability_batch()
      • compute_bond_angles_batch()
      • compute_torsion_angles_batch()
      • compute_quaternions_from_rotation_matrices()
      • compute_global_steinhardt_order_parameters_batch()
      • compute_best_fit_plane_batch()
      • compute_planarity_metrics_batch()
      • compute_fragment_pairwise_vectors_and_distances_batch()
      • Geometric Calculations and Descriptors
      • Core Functions
        • Bond Angle Calculations
        • Torsion Angle Calculations
        • Bond Rotatability Analysis
        • Planarity Analysis
        • Crystallographic Analysis
        • Order Parameter Analysis
        • Coordinate Transformations
        • Fragment Pairwise Analysis
      • Performance Optimization
      • Error Handling and Validation
      • Integration Examples
      • Cross-References
    • fragment_utils module
      • Dependencies
      • identify_rigid_fragments_batch()
      • prepare_fragments_batch()
      • compute_center_of_mass_batch()
      • compute_centroid_batch()
      • compute_inertia_tensor_batch()
      • compute_quadrupole_tensor_batch()
      • Molecular Fragment Analysis and Processing
      • Fragment Identification
        • identify_rigid_fragments_batch()
        • prepare_fragments_batch()
      • Center Calculations
        • compute_center_of_mass_batch()
        • compute_centroid_batch()
      • Tensor Analysis
        • compute_inertia_tensor_batch()
        • compute_quadrupole_tensor_batch()
      • Shape Descriptors and Analysis
      • Performance Optimization
      • Error Handling and Validation
      • Integration Examples
      • Cross-References
    • contact_utils module
      • Dependencies
      • compute_symmetric_contacts_batch()
      • compute_symmetric_hbonds_batch()
      • compute_contact_is_hbond()
      • compute_contact_fragment_indices_batch()
      • compute_contact_atom_to_central_fragment_com_batch()
      • Intermolecular Contact Analysis and Symmetry Expansion
      • Core Contact Functions
        • compute_symmetric_contacts_batch()
      • Hydrogen Bond Analysis
        • compute_symmetric_hbonds_batch()
      • Contact Classification and Validation
        • compute_contact_is_hbond()
      • Fragment-Level Contact Analysis
        • compute_contact_fragment_indices_batch()
        • compute_contact_atom_to_central_fragment_com_batch()
      • Advanced Contact Analysis
      • Performance Optimization
      • Error Handling and Validation
      • Integration Examples
      • Cross-References
    • cell_utils module
      • Dependencies
      • compute_scaled_cell()
      • compute_cell_matrix_batch()
      • Crystallographic Unit Cell Transformations and Matrix Operations
      • Core Functions
        • compute_cell_matrix_batch()
        • compute_scaled_cell()
      • Advanced Cell Operations
      • Performance Optimization
      • Error Handling and Validation
      • Integration Examples
      • Cross-References
    • symmetry_utils module
      • Dependencies
      • parse_sym_op()
      • invert_sym_op()
      • add_symmetry_matrices()
      • add_inter_cc_symmetry()
      • add_inter_hb_symmetry()
      • Crystallographic Symmetry Operations and Parsing
      • Core Functions
        • parse_sym_op()
        • invert_sym_op()
      • Batch Symmetry Processing
        • add_symmetry_matrices()
      • Contact-Specific Symmetry Functions
        • add_inter_cc_symmetry()
        • add_inter_hb_symmetry()
      • Advanced Symmetry Analysis
      • Performance Optimization
      • Error Handling and Validation
      • Integration Examples
      • Cross-References
    • data_reader module
      • Dependencies
      • RawDataReader
        • RawDataReader.h5_in
        • RawDataReader.read_crystal_parameters()
        • RawDataReader.read_atoms()
        • RawDataReader.read_bonds()
        • RawDataReader.read_intermolecular_contacts()
        • RawDataReader.read_intermolecular_hbonds()
        • RawDataReader.read_intramolecular_contacts()
        • RawDataReader.read_intramolecular_hbonds()
        • RawDataReader.__init__()
        • RawDataReader.read_crystal_parameters()
        • RawDataReader.read_atoms()
        • RawDataReader.read_bonds()
        • RawDataReader.read_intermolecular_contacts()
        • RawDataReader.read_intermolecular_hbonds()
        • RawDataReader.read_intramolecular_contacts()
        • RawDataReader.read_intramolecular_hbonds()
      • HDF5 Raw Data Reading and Batch Loading
      • RawDataReader Class
        • RawDataReader
      • Crystal Parameter Reading
        • RawDataReader.read_crystal_parameters()
      • Atomic Data Reading
        • RawDataReader.read_atoms()
      • Bond Data Reading
        • RawDataReader.read_bonds()
      • Contact Data Reading
        • RawDataReader.read_intermolecular_contacts()
        • RawDataReader.read_intermolecular_hbonds()
      • Intramolecular Data Reading
        • RawDataReader.read_intramolecular_contacts()
        • RawDataReader.read_intramolecular_hbonds()
      • Advanced Usage Patterns
      • Error Handling and Diagnostics
      • Performance Optimization
      • Cross-References
    • data_writer module
      • Dependencies
      • RawDataWriter
        • RawDataWriter.h5_out
        • RawDataWriter.write_raw_crystal_data()
        • RawDataWriter.write_raw_atom_data()
        • RawDataWriter.write_raw_bond_data()
        • RawDataWriter.write_raw_intramolecular_contact_data()
        • RawDataWriter.write_raw_intramolecular_hbond_data()
        • RawDataWriter.__init__()
        • RawDataWriter.write_raw_crystal_data()
        • RawDataWriter.write_raw_atom_data()
        • RawDataWriter.write_raw_bond_data()
        • RawDataWriter.write_raw_intramolecular_contact_data()
        • RawDataWriter.write_raw_intramolecular_hbond_data()
      • ComputedDataWriter
        • ComputedDataWriter.h5_out
        • ComputedDataWriter.write_computed_crystal_data()
        • ComputedDataWriter.write_computed_atom_data()
        • ComputedDataWriter.write_computed_bond_data()
        • ComputedDataWriter.write_computed_molecule_data()
        • ComputedDataWriter.write_computed_intermolecular_contact_data()
        • ComputedDataWriter.write_computed_intermolecular_hbond_data()
        • ComputedDataWriter.__init__()
        • ComputedDataWriter.write_computed_crystal_data()
        • ComputedDataWriter.write_computed_atom_data()
        • ComputedDataWriter.write_computed_bond_data()
        • ComputedDataWriter.write_computed_molecule_data()
        • ComputedDataWriter.write_computed_intermolecular_contact_data()
        • ComputedDataWriter.write_computed_intermolecular_hbond_data()
        • ComputedDataWriter.write_computed_fragment_data()
      • HDF5 Data Writing and Storage Management
      • Writer Classes Overview
      • RawDataWriter Class
        • RawDataWriter
      • Crystal Data Writing
        • RawDataWriter.write_raw_crystal_data()
      • Atomic Data Writing
        • RawDataWriter.write_raw_atom_data()
      • Bond Data Writing
        • RawDataWriter.write_raw_bond_data()
      • Contact Data Writing
        • RawDataWriter.write_raw_intramolecular_contact_data()
        • RawDataWriter.write_raw_intramolecular_hbond_data()
      • ComputedDataWriter Class
        • ComputedDataWriter
      • Computed Data Writing Methods
        • ComputedDataWriter.write_computed_crystal_data()
        • ComputedDataWriter.write_computed_atom_data()
        • ComputedDataWriter.write_computed_bond_data()
        • ComputedDataWriter.write_computed_molecule_data()
        • ComputedDataWriter.write_computed_fragment_data()
      • Advanced Writing Patterns
      • Data Type Management
      • Performance Optimization
      • Cross-References
    • hdf5_utils module
      • Dependencies
      • initialize_hdf5_file()
      • write_structure_group()
      • HDF5 File Initialization and Management Utilities
      • Core Functions
        • initialize_hdf5_file()
        • write_structure_group()
      • Advanced HDF5 Management
      • Performance Optimization
      • Integration Examples
      • Cross-References
    • dimension_scanner module
      • Dependencies
      • scan_max_dimensions()
      • HDF5 Dataset Dimension Analysis and Optimization
      • Core Functions
        • scan_max_dimensions()
    • Module Overview
      • Core Modules
      • Extraction Pipeline
      • Processing Utilities
      • Input/Output
      • Validation
    • Quick Reference
      • Most Common Classes
        • crystal_analyzer.CrystalAnalyzer
        • csa_config.ExtractionConfig
        • csd_operations.CSDOperations
        • structure_data_extractor.StructureDataExtractor
        • structure_post_extraction_processor.StructurePostExtractionProcessor
      • Key Functions
        • csa_config.load_config
        • geometry_utils.compute_bond_angles_batch
        • fragment_utils.identify_rigid_fragments_batch
        • contact_utils.compute_symmetric_contacts_batch
        • cell_utils.compute_cell_matrix_batch
      • Data Structures
        • csd_structure_validator.StructureValidationResult
        • structure_post_extraction_processor.CrystalParams
        • structure_post_extraction_processor.AtomParams
        • structure_post_extraction_processor.BondParams
    • Usage Patterns
      • Basic Pipeline Setup
      • Custom Processing
      • Batch Geometric Calculations
      • Data Access Patterns
      • Configuration Management
      • Error Handling Patterns
      • Performance Optimization
    • Module Dependencies
    • Import Patterns
    • Common Workflows
    • Advanced Usage Examples
    • Troubleshooting
    • See Also

Technical Details

  • Performance Architecture
    • Data Storage Design
  • HDF5 Schema Architecture
    • Algorithm Details
  • Similarity Clustering Algorithm
  • Geometric Calculation Algorithms
  • Fragment Analysis Algorithms
  • Contact Detection Algorithms
    • Performance Optimization Details
  • GPU Memory Management
    • Testing and Validation
  • Unit Testing Framework
    • Documentation and Maintenance
  • Code Documentation Standards
    • Architecture Overview
    • Algorithms and Methods
    • Implementation Details
    • System Architecture
  • High-Level Design
  • Core Components
Crystal Structure Analysis (CSA)
  • Python Module Index

Python Module Index

c | d | f | g | h | s
 
c
cell_utils
contact_utils
crystal_analyzer
csa_config
csa_main
csd_operations
 
d
data_reader
data_writer
dimension_scanner
 
f
fragment_utils
 
g
geometry_utils
 
h
hdf5_utils
 
s
structure_data_extractor
structure_post_extraction_processor
symmetry_utils

© Copyright 2025, Nikolaos Galanakis . Last updated on Jul 04, 2025.

Built with Sphinx using a theme provided by Read the Docs.