CSP Database API

Introduction

The main class of the ccdc.csp.database module is ccdc.csp.database.CspDatabase.

A ccdc.csp.database.CspDatabase represents a database of crystal structure predictions. The database can hold predictions for many different molecules, with sets of predictions for a particular molecule being organised into landscapes.

Connecting to CSP databases

A CSP database actually consists of two distinct parts with different connection methods, this is a temporary situation which will be replaced with a single database in the future. The two databases are identified as follows:

  1. A crystal structure database file in csdsqlx format, which must be visible in the file system on which a CSPC python script is run. This database file will be created if it does not already exist. This database file can be tested, and its contents examined, by opening it in Mercury.

  2. A CSP metadata database which is accessed via a web-service URL. This web-service will usually be hosted on a non-public web server that is visible to CSP users. The web-service URL will normally consist of a hostname and port number, optionally there may be some extra path. This URL should be supplied by your local system administrators. The URL can be tested by appending “/api/CSPMetadata” to it and opening the result in a web browser. You should see a JSON formatted list as a response if the service is working correctly, the list will be empty “[]” if no predictions have been added to the database yet.

Retrieving prediction data from a database:

# open a database
db = CspDatabase("my_predictions.csdsqlx", "http://my.prediction.metadata.server:2468")

# get the landscape names held in the database
print(db.landscape_names)

# print the energy and calculated density values for the entries in a landscape named "XXV"
for id in db.prediction_identifiers('XXV'):
    prediction = db.prediction(id)
    print(prediction.classification_energy_relative, prediction.crystal.calculated_density)

Such databases should be populated by the utilities.import_csp_landscape.import_csp_landscape script.

API

class ccdc.csp.database.CspDatabase(structure_db_filename, metadata_host_url)[source]

A database of crystal structure predictions.

class LandscapeSummary(summary)[source]

Summary information about a CSP landscape

property experimental_refcodes

Return the experimental refcodes that were matched

property hbond_inter_frequency

Return the intermolecular hydrogen bond frequency for this landscape

property hbond_intra_frequency

Return the intramolecular hydrogen bond frequency for this landscape

property lowest_energy_prediction_name

Return the lowest energy prediction name

property matching_prediction_names

Return the prediction names that matched experimentally observed structures

property max_0K_relative_energy

Return the maximum relative lattice energy at 0K for this landscape

property molecular_shape_descriptor_average_max

Return the maximum molecular shape descriptor average for this landscape

property molecular_shape_descriptor_average_min

Return the minimum molecular shape descriptor average for this landscape

property molecular_shape_descriptor_difference_max

Return the maximum molecular shape descriptor difference for this landscape

property molecular_shape_descriptor_difference_min

Return the minimum molecular shape descriptor difference for this landscape

property number_exp_matches

Return the number of predictions with matches against experimentally observed structures

property number_predictions_0K

Return the number of predictions at temperature 0K

property number_simulated_T_non_zero

Return the number of simulated temperatures above 0K

property packing_coefficient_max

Return the maximum packing coefficient for this landscape

property packing_coefficient_min

Return the minimum packing coefficient for this landscape

property spacegroup_frequency

Return the spacegroup frequency counts for this landscape

property total_number_predictions

Return the total number of predictions

property void_volume_max

Return the maximum void volume, in cubic Angstroms, for this landscape

property void_volume_min

Return the minimum void volume, in cubic Angstroms, for this landscape

property z_prime_frequency

Return the Z’ frequency counts for this landscape

cross_reference(observed_structure_db, log_file=None)[source]

Cross reference this CSP database with a database of observed crystal structures.

Parameters

  • observed_structure_db – a crystal structure database containing experimentally observed structures

  • log_file – the name of a log file

property landscape_names

Return the names of landscapes in the database.

landscape_summary(landscape_name: str) → LandscapeSummary[source]

Return a summary of the named landscape

prediction(identifier: str) → Prediction[source]

Return a Prediction by identifier.

prediction_identifiers(landscape_name: str)[source]

Return the prediction identifiers in a named landscape in the database.