XspectraCrystalWorkChain: Enable Symmetry Data Inputs

[PNOGillespie]

Overview

In this PR we add an input namespace for the XspectraCrystalWorkChain which allows the user to define the spacegroup and equivalent sites data for the incoming structure, thus instructing the WorkChain to generate structures and run calculations for only the sites specified. The new symmetry_data input requires entries for the system's spacegroup number (Int) and equivalent sites data (Dict). The former must simply be a valid spacegroup number (1-230) while the latter must contain an entry for each site (in the format site_<index>_<element>), where the minimal data required are the kind_name, element, site_index, and multiplicity.

In order to not be too restrictive on the user and make it easier to use external packages to build input symmetry data, we limit input validation to simple checks which ensure that the required data are present and that the data provided won't cause an obvious crash. Thus beyond the minimum required information, any extra data provided in the entries of the equivalent_sites_data node will be kept in case they may be needed by the user outside of the WorkChain (e.g. the list of symmetrically equivalent sites, which the WorkChain doesn't need).

Changes

• Adds the symmetry_data input namespace to XspectraCrystalWorkChain, which the WorkChain will use to generate structures and set the list of polarisation vectors to calculate.
• Adds input validation steps for the symmetry data to check for required information and for entries which may cause a crash, though does not check for issues beyond this in order to maximise flexibility of use.
• Fixes an oversight in get_xspectra_structures where the supercell entry was not returned to the outputs when external symmetry data were provided by the user.

[PNOGillespie]

Hi @superstar54, not sure what the issue with the docs is. If you could take a look at it (or ask someone who would know more about it), that would be much appreciated.

As always, I'm available to make changes as requested.

[superstar54]

Thanks @PNOGillespie for the PR. I added a few minor suggestions.

[PNOGillespie]

Hi @superstar54, thanks for the review. I've committed your suggestions, as well as a couple of other things which I noticed on taking a second look at the input validation steps.

let me know if you need anything else.

[PNOGillespie]

Hi @superstar54, let me know if there are any other changes that you think are necessary for this PR.

[superstar54]

Hi @PNOGillespie , please fix the failed test, and then we can merge.

[PNOGillespie]

Hi @PNOGillespie , please fix the failed test, and then we can merge.

Hi @superstar54. Looking at the output from the failed test, it seems to be a more general issue with the GitHub workflow - I see exactly the same thing in the recent PR by @yakutovicha (#1029).

Unfortunately, I don't know what the problem is. When I compile the docs in my docker container, everything runs fine, but here it returns a few errors:

• WARNING: toctree contains reference to nonexisting document 'home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso/checkouts/1028/docs/source/reference/api/auto/aiida_quantumespresso/ - repeated for each entry in the API
• /home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso/checkouts/1028/docs/source/reference/api/auto/aiida_quantumespresso/calculations/cp/index.rst:26: WARNING: py:obj reference target not found: base.CalcJob
• /home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso/checkouts/1028/docs/source/reference/api/auto/aiida_quantumespresso/parsers/parse_xml/pw/parse/index.rst:71: WARNING: more than one target found for cross-reference 'XMLUnsupportedFormatError': aiida_quantumespresso.parsers.neb.XMLUnsupportedFormatError, aiida_quantumespresso.parsers.parse_xml.exceptions.XMLUnsupportedFormatError, aiida_quantumespresso.parsers.parse_xml.versions.XMLUnsupportedFormatError

Do we know anyone who might be able to diagnose and fix the problem?

[superstar54]

Hi @mbercx , Could you please help check why the docs failed?

[sphuber]

Pretty sure the + signs are superfluous since all strings are encapsulated by ()

Suggested change

	help=(
	'Input namespace to define equivalent sites and spacegroup number for the system. If defined, will '
	+ 'skip symmetry analysis and structure standardization. Use *only* if symmetry data are known'
	+ 'for certain. Requires ``spacegroup_number`` (Int) and ``equivalent_sites_data`` (Dict) to be'
	+ 'defined separately. All keys in `equivalent_sites_data` must be formatted as "site_<site_index>".'
	+ 'See docstring of `get_xspectra_structures` for more information about inputs.'
	)
	)
	help=(
	'Input namespace to define equivalent sites and spacegroup number for the system. If defined, will '
	'skip symmetry analysis and structure standardization. Use *only* if symmetry data are known '
	'for certain. Requires ``spacegroup_number`` (Int) and ``equivalent_sites_data`` (Dict) to be '
	'defined separately. All keys in `equivalent_sites_data` must be formatted as "site_<site_index>". '
	'See docstring of `get_xspectra_structures` for more information about inputs.'
	)
	)

[sphuber]

I notice that the rest of the validator also raises exceptions, but the proper usage of a port validator is to return a string in case of a problem. So all raise ValidationError should simply be replaced by return.

[PNOGillespie]

Hi @superstar54 and @sphuber, thanks to both of you for the feedback. I've added @sphuber's proposed changes (as well as fixing a little formatting whoopsy that I spotted in the help string that you were pointing to).

Let me know if any other changes are needed.

[sphuber]

Thanks @PNOGillespie