Entry API

Introduction

The main class of the ccdc.entry module is ccdc.entry.Entry.

A ccdc.entry.Entry is often a CSD entry. It contains attributes that are beyond the concepts of chemistry and crystallography. An example of such an attribute would be the publication details of a CSD entry.



>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> abebuf = csd_reader.entry('ABEBUF')
>>> print(abebuf.publication)  
Citation(authors='S.W.Gordon-Wylie, E.Teplin, J.C.Morris, M.I.Trombley, S.M.McCarthy, W.M.Cleaver, G.R.Clark',
         journal='Journal(Crystal Growth and Design)',
         volume='4', year=2004, first_page='789',
         doi='10.1021/cg049957u')

However, a ccdc.entry.Entry does not necessarily have to be a CSD entry. If, for example, a sdf file is read in using a ccdc.io.EntryReader then the sdf tags will be added to a dictionary-like object named attributes of the entry. Entries read in from CIF files will also contain attributes with the raw data from the CIF file.

See also

Descriptive entry documentation.

API

Entry

class ccdc.entry.Entry(_entry=None)[source]

A database entry.

class CrossReference(_xr)[source]

A cross-reference between entries in the database.

property identifiers

A tuple containing identifiers of the cross-referenced entries.

property scope

Whether the cross-reference applies to the individual identifier or the family of related identifiers.

property text

The text of the cross-reference.

property type

The type of cross-reference.

Available types are ‘Unknown’, ‘Racemate’, ‘Stereoisomer’, ‘Isomer’, ‘Reinterpretation of’, ‘Reinterpretation ref’, and ‘Coordinates ref’.

property analogue

Analogue information.

property bioactivity

Recorded information about bioactivity if available otherwise None.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> aadmpy10 = csd_reader.entry('AADMPY10')
>>> print(aadmpy10.bioactivity)
antineoplastic activity
property calculated_density

The density.

property ccdc_number

The CCDC deposition number.

>>> from ccdc.io import EntryReader
>>> entry_reader = EntryReader('CSD')
>>> abebuf = entry_reader.entry('ABEBUF')
>>> print(abebuf.ccdc_number)
241370
property chemical_name

The chemical name of the entry.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> acsala13 = csd_reader.entry('ACSALA13')
>>> print(acsala13.chemical_name)
2-acetoxybenzoic acid
property chemical_name_as_html

The chemical name of the entry formatted as HTML.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> e = csd_reader.entry('AACRHA')
>>> print(e.chemical_name_as_html)
Tetra-ammonium bis(bis(μ<sub>2</sub>-acetato-O,O')-bromo-rhodium(iv)) dibromide
property color

The colour of the crystal if given, otherwise None.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> acesor = csd_reader.entry('ACESOR')
>>> print(acesor.color)
yellow
property component_inchis

The list of component InChIs of this entry

Where available, the InChIs of the entry components are returned. Each InChI includes the following attributes:

ivar inchi:

the InChI string

ivar key:

the InChI key

property cross_references

The tuple of ccdc.entry.Entry.CrossReference for this entry. These are cross-references between entries of the CSD.

property crystal

The ccdc.crystal.Crystal contained in a database entry.

property database_name

The name of the source database.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> acesor = csd_reader.entry('ACESOR')
>>> print(acesor.database_name)  
as536be_ASER
property deposition_date

The date when this entry was deposited as a datetime.date object or None if the date is not available.

property disorder_details

Information about any disorder present if given otherwise None.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> abacir = csd_reader.entry('ABACIR')
>>> print(abacir.disorder_details)
O4 and O4A disordered over two sites with occupancies 0.578:0.422.
property disordered_molecule

The ccdc.molecule.Molecule contained in a database entry, including disordered atoms.

property formatted_melting_point_range

Get the formatted melting point in default units.

Returns:

a three-item tuple containing the minimum value, maximum value and units string. If the melting point is a single value the min and max will be set to the same value.

property formatted_melting_point_text

Get the formatted melting point descriptive text.

property formula

The published chemical formula in an entry.

If no published chemical formula is available it will be calculated from the molecule.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> aacani10 = csd_reader.entry('AACANI10')
>>> print(aacani10.formula)
C10 H18 N2 Ni1 O5,2(H2 O1)
static from_molecule(mol, **attributes)[source]

Construct an entry from a molecule, using the keyword arguments as attributes.

static from_string(s, format='')[source]

Create an entry from a string representation.

The format will be auto-detected if not specified.

Parameters:

  • s – string representation of an entry, crystal or molecule

  • format – one of ‘mol2’, ‘sdf’, ‘mol’, ‘cif’, ‘mmcif’ or ‘smiles’

Returns:

a ccdc.entry.Entry

Raises:

TypeError if the format string is not ‘’, ‘mol2’, ‘sdf’, ‘mol’, ‘cif’, ‘mmcif’ or ‘smiles’.

Raises:

RuntimeError if the string representation is incorrectly formatted

property habit

The crystal habit.

property has_3d_structure

Whether the entry has 3d information.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> aqefor = csd_reader.entry('AQEFOR')
>>> aqefor.has_3d_structure
False
property has_disorder

Whether the structure has disorder.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> abacir = csd_reader.entry('ABACIR')
>>> abacir.has_disorder
True
property heat_capacity

Get or set the heat capacity.

Returns:

a two-item tuple containing the heat capacity value and units

When setting, pass a tuple with either a single value, or a value and a units string.

>>> from ccdc.entry import Entry
>>> e=Entry.from_string("OCO")
>>> e.heat_capacity=(54.55,)
>>> e.heat_capacity
(54.55, '')
>>> e.heat_capacity=(54.55,'J/K')
>>> e.heat_capacity
(54.55, 'J/K')
property heat_capacity_notes

Get or set the notes on the heat capacity

>>> from ccdc.entry import Entry
>>> e=Entry.from_string("OCO")
>>> e.heat_capacity_notes
''
>>> e.heat_capacity_notes='from Wikipedia, at 189.78K'
>>> e.heat_capacity_notes
'from Wikipedia, at 189.78K'
property heat_of_fusion

Get or set the heat of fusion

A tuple is required to set this. The first item is a value or lower bound for heat of fusion. The optional second item is an upper bound for heat of fusion, or None. The optional third item is units for the heat of fusion.

>>> from ccdc.entry import Entry
>>> e=Entry.from_string("OCO")
>>> e.heat_of_fusion = (9.019,)
>>> e.heat_of_fusion
(9.019, 9.019, '')
>>> e.heat_of_fusion = (9,9.1)
>>> e.heat_of_fusion
(9.0, 9.1, '')
>>> e.heat_of_fusion = (9,9.1,'KJ/mol')
>>> e.heat_of_fusion
(9.0, 9.1, 'KJ/mol')
property heat_of_fusion_notes

Get or set the notes of heat of fusion

property identifier

The string identifier of the entry, e.g. ‘ABEBUF’.

property input_melting_point_range

Set or get the original input unparsed melting point range.

When setting pass in a tuple e.g. (285,) no max value provided, use the default units. (28.2, None, “deg.C”) single value, use degrees centigrade (28.2, 29.5, “deg.C”) min, max, use degrees centigrade (275, 278) min and max, default units (275, 278, “K”) min and max in Kelvin

property input_melting_point_text

Get or set the input melting point text.

property is_organic

Whether the structure is organic.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> aacani10 = csd_reader.entry('AACANI10')
>>> aacani10.is_organic
False
property is_organometallic

Whether the structure is organometallic.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> aacani10 = csd_reader.entry('AACANI10')
>>> aacani10.is_organometallic
True
property is_polymeric

Whether the structure contains polymeric bonds.

>>> from ccdc.io import EntryReader
>>> csd = EntryReader('CSD')
>>> abacuf = csd.entry('ABACUF')
>>> abacuf.is_polymeric
True
property is_powder_study

Whether or not the crystal determination was performed on a powder study

>>> from ccdc.io import EntryReader
>>> csd = EntryReader('csd')
>>> print(csd.entry('AABHTZ').is_powder_study)
False
>>> print(csd.entry('ACATAA').is_powder_study)
True
property melting_point

Melting point of the crystal if given otherwise None.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> acsala13 = csd_reader.entry('ACSALA13')
>>> print(acsala13.melting_point)
408.5 K
property melting_point_default_units

Return the default melting point units.

property melting_point_display_string

The parsed and formatted melting point string.

property molecule

The ccdc.molecule.Molecule contained in a database entry.

property peptide_sequence

The peptide sequence of the entry if any.

property phase_transition

Phase transition of the entry.

property polymorph

Polymorphic information about the crystal if given otherwise None.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> acsala13 = csd_reader.entry('ACSALA13')
>>> print(acsala13.polymorph)
polymorph II
property predicted_properties: CrystalPredictedProperties | None

Returns the predicted properties for the entry, or None if they have not been provided.

property pressure

The experimental pressure of the crystallisation of the entry, where known.

This is a text field. If None the experiment was performed at ambient pressure or not recorded.

>>> from ccdc.io import EntryReader
>>> csd = EntryReader('csd')
>>> print(csd.entry('AABHTZ').pressure)
None
>>> print(csd.entry('ABULIT03').pressure)
1.4 GPa
property previous_identifier

Previous identifier if any.

>>> from ccdc.io import EntryReader
>>> entry_reader = EntryReader('CSD')
>>> acpret03 = entry_reader.entry('ACPRET03')
>>> print(acpret03.identifier)
ACPRET03
>>> print(acpret03.previous_identifier)
DABHUJ
property publication

The first publication of a structure.

This attribute gives the publication details of a CSD entry, expressed as a tuple of (authors, journal, volume, year, first_page, doi).



>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> aqefor = csd_reader.entry('AQEFOR')
>>> print(aqefor.publication) 
Citation(authors='M.E.Bluhm, M.Ciesielski, H.Gorls, O.Walter, M.Doring',
         journal='Journal(Inorganic Chemistry)', volume='42', year=2003,
         first_page='8878', doi='10.1021/ic034773a')
Return type:

Citation

property publications

All publications of the entry.

property r_factor

Resolution of crystallographic determination, given as a percentage value.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> acsala13 = csd_reader.entry('ACSALA13')
>>> acsala13.r_factor
16.22
property radiation_source

The radiation source of the crystal’s determination.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> aabhtz = csd_reader.entry('AABHTZ')
>>> aabhtz.radiation_source
'X-ray'
>>> csd_reader.entry('ABINOR01').radiation_source
'Neutron'
property remarks

Any remarks on the entry registered by the editors of the database.

These may include details like a US Patent number:

>>> from ccdc.io import EntryReader
>>> csd = EntryReader('csd')
>>> print(csd.entry('ARISOK').remarks)
U.S. Patent: US 6858644 B2

or reflect editorial decisions:

>>> print(csd.entry('ABAPCU').remarks)
The position of the hydrate is dubious. It has been deleted
property solubility_data

Get or set the solubility data, a list of ccdc.entry.SolubilityMeasurement

>>> from ccdc.entry import Entry, SolubilityMeasurement
>>> e=Entry.from_string('CC(C)Cc1ccc(cc1)C(C)C(O)=O')
>>> sol = SolubilityMeasurement('21-22', 25, 'mg/L', 'deg.C', 'from PubChem')
>>> sol.add_solvent('water', 100)
>>> e.solubility_data = [sol]
>>> e.solubility_data
[SolubilityMeasurement(21 - 22, 25.0, "mg/L", "deg.C", from PubChem)]
>>> e.solubility_data[0].solvents
(('water', 100.0),)
property solvent

Recrystallisation solvent.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> rechul = csd_reader.entry('REKHUL')
>>> print(rechul.solvent)
pentane
property source

The source of the compound(s) in the entry.

>>> from ccdc.io import EntryReader
>>> entry_reader = EntryReader('CSD')
>>> fifdut = entry_reader.entry('FIFDUT')
>>> print(fifdut.source)
dried venom of Chinese toad Ch'an Su
property synonyms

List containing any recorded synonyms for the entry.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> acsala13 = csd_reader.entry('ACSALA13')
>>> print(' '.join(acsala13.synonyms)) 
Aspirin
DrugBank: DB00945
property synonyms_as_html

Tuple containing any recorded synonyms for the entry formatted as HTML.

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> aalpro = csd_reader.entry('AALPRO')
>>> print(aalpro.synonyms_as_html[0])
α-Allylprodine hydrochloride
property temperature

Experimental temperature of the entry

>>> from ccdc.io import EntryReader
>>> csd_reader = EntryReader('CSD')
>>> acsala13 = csd_reader.entry('ACSALA13')
>>> print(acsala13.temperature)
at 100 K
to_string(format='mol2')[source]

Return a string representation of an entry.

Parameters:

format – ‘mol2’, ‘sdf’, ‘mol’, ‘cif’, ‘mmcif’ or ‘smiles’

Return type:

string

Raises:

TypeError if the format is not ‘mol2’, ‘sdf’, ‘mol’, ‘cif’, ‘mmcif’ or ‘smiles’

Journals

class ccdc.entry.Journal(_journal)[source]

Information about a journal held in the CSD.

property abbreviated_name

The abbreviated name of the journal.

property abbreviated_translated_name

The abbreviated translated name of the journal.

property eissn

The electronic international sequence number of the journal.

property end_year

The date of termination of publication of the journal.

property full_name

The full name of the journal.

property image_url

The URL of an image of the journal.

property international_coden

The ASTM international identifier of the journal.

property issn

The international sequence number of the journal.

property language_name

The name of the journal’s original language (where possible).

property name

The name of the journal.

property publisher_name

The name of the publisher of the journal.

property start_year

The year of first publication of the journal.

property state

Whether or not the journal is current.

property translated_name

The translated name of the journal.

property url

The URL of the journal on the publisher’s website.

class ccdc.entry.JournalList(database)[source]

The collection of journals read from a database.

by_abbreviated_name(value)[source]

The unique journal with a given abbreviated name or None.

by_full_name(value)[source]

The unique journal with a given full name or None.

match_abbreviated_name(regexp)[source]

Those journals matching a regular expression on the abbreviated name.

match_full_name(regexp)[source]

Those journals whose full name is matched by the regexp.

Those journals any of whose names contain the given pattern.

class ccdc.entry.SolubilityMeasurement(solubility, temperature, solubility_unit='mg/mL', temperature_unit='deg.C', notes='')[source]

A solubility measurement.

Parameters:

  • solubility – a solubilty value, range tuple or string, see ccdc.entry.SolubilityMeasurement.Solubility

  • temperature – a measurement temperature value.

  • solubility_unit – the solubility units, default mg/mL.

  • temperature_unit – the temperature units, default deg.C.

  • notes – notes for this measurement.

class Solubility(solubility)[source]

A solubility value range.

This can be created from a single value. Or from a tuple of (lower, upper) bound values. Or from a string describing the range such as “< 15” or “3 - 8”.

property max

The maximum solubility value, or None if there is no maximum value.

property min

The minimum solubility value, or None if there is no minimum value.

add_solvent(solvent, ratio)[source]

Add a solvent-ratio to the solubility measurement

Run this method for each solvent.

Parameters:

  • solvent – name of solvent

  • ratio – percentage of solvent

property notes

The solubility measurement notes

property solubility

The solubility value, a ccdc.entry.SolubilityMeasurement.Solubility

property solubility_unit

The solubility unit

property solvents

The list of solvents and percentages

Each item is returned as a tuple of (name, percentage).

property temperature

The temperature value

property temperature_unit

The temperature unit

Predicted Properties

class ccdc.entry.CrystalPredictedProperties(_properties=None)[source]

A container for different types of predicted properties of a database entry.

Currently ccdc.entry.SemiconductorPredictedProperties is the only type implemented.

property semiconductor_properties: SemiconductorPredictedProperties | None

Returns the predicted semiconductor properties for the entry, or None if they have not been provided.

class ccdc.entry.SemiconductorPredictedProperties(_semiconductor=None)[source]

A container for the predicted semiconductor properties of a database entry.

Each of the properties is optional, and will return None instead of a value if it has not been set.

Semiconductor property calculations are described in https://onlinelibrary.wiley.com/doi/10.1002/adfm.202001906 Breifly, HOMO_LUMO, reorganization energy, transfer integral, and dynamic disorder, were calculated at the B3LYP/3-21G* level, calibrated against those at the B3LYP/6-31G* level, as described in this paper: [https://pubs.rsc.org/en/content/articlelanding/2019/ee/c9ee01508f]. Excited state data (singlet and triplet states, and oscillator strengths) are computed at the M06-2X/def2-SVP level of theory.

property dynamic_disorder: float | None

A global measure of the fluctuations of the transfer integrals at room temperature, in kJ/mol. A large (>10 kJ/mol) value is detrimental to charge mobility in organic semiconductors. More information on how this value was calculated is provided at https://pubs.rsc.org/en/content/articlelanding/2020/mh/d0mh01159b, please cite this work if you find it useful in your research

property hole_reorganization_energy: float | None

The impact of vibrations from molecular relaxations (intra-molecular modes) on site energy in kJ/mol. Specifically, this is the reorganization energy for the process of Neutral Molecule to Oxidized Molecule, meaning how much the energy is lowered when a hole is formed in a molecule and the geometry relaxes from the neutral to the +1 charged equilibrium geometry. More information on how this value was calculated is provided at https://pubs.aip.org/aip/jcp/article/152/19/190902/199058/Modeling-charge-transport-in-high-mobility, please cite this work if you find it useful in your research

property homo_lumo_gap: float | None

The difference in energy between the Highest Occupied Molecular Orbital (HOMO), and Lowest Unoccupied Molecular Orbital (LUMO) in kJ/mol. A requirement of visible light active materials is that the gap is < 385 kJ/mol. More information on how this value was calculated is provided at https://pubs.rsc.org/en/content/articlelanding/2019/EE/C9EE01508F, please cite this work if you find it useful in your research.

property singlet_state_1_energy: float | None

Energy of first singlet (S1) state in kJ/mol.

This is the lowest energy excited electronic state with unpaired electrons having opposite spin. A requirement of singlet fission materials is for S1>=2*T1, whilst Thermally Activated Delayed Fluorescence (TADF) materials require S1~T1. More information on how this value was calculated is provided at https://pubs.rsc.org/en/content/articlelanding/2019/EE/C9EE01508F, please cite this work if you find it useful in your research. These values are the “as-calculated” values, the formula to calibrate calculations to experimental data is reported in the paper.

property singlet_state_1_oscillator_strength: float | None

Oscillator strength of the first singlet state f(S1). A requirement for many applications is that the material is optically bright, i.e. the computed oscillator strength is larger than 0.05. More information on how this value was calculated is provided at https://pubs.rsc.org/en/content/articlelanding/2019/EE/C9EE01508F, please cite this work if you find it useful in your research

property singlet_state_2_energy: float | None

Energy of the second singlet (S2) state in kJ/mol.

This is the second-lowest energy excited electronic state with unpaired electrons having opposite spin. More information on how this value was calculated is provided at https://www.nature.com/articles/s41597-022-01142-7 and https://pubs.rsc.org/en/content/articlelanding/2019/EE/C9EE01508F, please cite this work if you find it useful in your research

property singlet_state_2_oscillator_strength: float | None

Oscillator strength of second singlet state f(S2). A requirement for many applications is that the material is optically bright, i.e. the computed oscillator strength is larger than 0.05. More information on how this value was calculated is provided at https://pubs.rsc.org/en/content/articlelanding/2019/EE/C9EE01508F, please cite this work if you find it useful in your research

property transfer_integral: float | None

The largest transfer integral between two HOMO orbitals localized on to two neighboring molecules, (J1), in kJ/mol. This is the extent to which charge is able to be “transferred” from one molecule to another. A requirement of high mobility materials is that J1>10kJ/mol. More information on how this value was calculated is provided at https://pubs.acs.org/doi/epdf/10.1021/acs.chemmater.2c00281, please cite this work if you find it useful in your research

property triplet_state_1_energy: float | None

Energy of the first triplet state (T1) in kJ/mol.

This is the lowest energy excited electronic state with unpaired electrons having the same spin. A requirement of singlet fission materials is for S1>=2*T1, whilst Thermally Activated Delayed Flourescsnce (TADF) materials require S1~T1. More information on how this value was calculated is provided at https://pubs.rsc.org/en/content/articlelanding/2019/EE/C9EE01508F, please cite this work if you find it useful in your research

property triplet_state_2_energy: float | None

Energy of the second triplet state (T2) in kJ/mol.

This is the second-lowest energy excited electronic state with unpaired electrons having the same spin. A requirement of singlet fission materials is T2>2*T1 to avoid triplet-triplet fusion. More information on how this value was calculated is provided at https://pubs.rsc.org/en/content/articlelanding/2019/EE/C9EE01508F, please cite this work if you find it useful in your research