annotate pm_muairss_write.xml @ 1:150301c057b0 draft

planemo upload for repository https://github.com/muon-spectroscopy-computational-project/muon-galaxy-tools/main/pm_muairss_write commit 1f0d5da860dd5cd0ffceac7a292773ed53617324

<tool id="pm_muairss_write" name="PyMuonSuite AIRSS Generate" version="@TOOL_VERSION@+galaxy@WRAPPER_VERSION@" python_template_version="3.5" profile="22.01">
    <description>generate muonated structures</description>
    <macros>
        <!-- version of underlying tool (PEP 440) -->
        <token name="@TOOL_VERSION@">0.2.1</token>
        <!-- version of this tool wrapper (integer) -->
        <token name="@WRAPPER_VERSION@">1</token>
        <!-- citation should be updated with every underlying tool version -->
        <!-- typical fields to update are version, month, year, and doi -->
        <token name="@TOOL_CITATION@">
            @software{pymuon-suite,
                author = {Sturniolo, Simone and Liborio, Leandro and Chadwick, Eli and Murgatroyd, Laura and Laverack, Adam and {Muon Spectroscopy Computational Project}},
                license = {GPL-3.0},
                title = {{pymuon-suite}},
                url = {https://github.com/muon-spectroscopy-computational-project/pymuon-suite},
                version = {v0.2.1},
                month = {2},
                year = {2022},
                doi = {}
            }
        </token>
    </macros>
    <creator>
        <person givenName="Eli" familyName="Chadwick" url="https://github.com/elichad" identifier="https://orcid.org/0000-0002-0035-6475"/>
        <person givenName="Jyothish" familyName="Thomas" identifier="https://orcid.org/0000-0003-4724-6924"/>
        <organization url="https://muon-spectroscopy-computational-project.github.io/index.html" name="The Muon Spectroscopy Computational Project"/>
    </creator>
    <requirements>
        <requirement type="package" version="@TOOL_VERSION@">pymuonsuite</requirement>
        <requirement type="package" version="3.0">zip</requirement>
    </requirements>
    <required_files>
        <include type="literal" path="get_out_folder.py"/>
    </required_files>
    <command detect_errors="exit_code"><![CDATA[
        structure_name_internal="input_structure.$structure.ext" &&
        ln -s $structure \$structure_name_internal &&
        ln -s $params params.yaml &&
        #if str($iscastep.iscastep_sel)=="true":
            castep_param_name=\$(sed 's/ //g' <<< "$castep_param.name") &&
            ln -s $castep_param \$castep_param_name &&
            sed -i '/^castep_param: /{h;s/:.*/: $castep_param.name/};\${x;/^$/{s//castep_param: $castep_param.name/;H};x}' params.yaml &&
        #end if
        pm-muairss -t w \$structure_name_internal params.yaml &&
        out_folder="`python ${__tool_directory__}/get_out_folder.py`" &&
        #if str($iscastep.iscastep_sel)=="true":
            zip -r out_zip.zip \$out_folder params.yaml \$structure_name_internal \$castep_param_name &&
        #else if str($iscastep.iscastep_sel)=="false":
            zip -r out_zip.zip \$out_folder params.yaml \$structure_name_internal &&
        #end if
        #if $testing=="true" and str($iscastep.iscastep_sel)=="true":
            grep "castep_param" params.yaml > tree.txt &&
        #end if
        find \$out_folder >> tree.txt

    ]]></command>
    <inputs>
        <param type="data" name="structure" label="Structure file" format="cell, cif, xyz, extxyz" help="The structure to add muons to. The original file will be preserved. Accepted file types: CELL, CIF, XYZ (standard or extended)."/>
        <param type="data" name="params" label="YAML parameter file" format="yaml" help="YAML parameters for this and subsequent tools. You can create this file using the [YAML config generator] tool."/>
        <conditional name="iscastep">
            <param type="boolean" value="false" name="iscastep_sel" label="Does your configuration use the CASTEP calculator?" help="Select 'Yes' if the 'calculator' parameter is set to 'castep' in your chosen YAML file (not case sensitive).">
                <option value="false">no</option>
                <option value="true">yes</option>
            </param>
            <when value="true">
                <param type="data" name="castep_param" label="CASTEP parameter file" format="txt,yaml" help="CASTEP parameters (.param file) for the optimisation stage. These parameters will be copied for each muonated structure."/>
            </when>
            <when value="false"/>
        </conditional>
        <param type="hidden" name="testing" label="Test mode" value="false"/>
    </inputs>
    <outputs>
        <data label="Muonated $structure.name using $params.name" name="muonated_structures" format="zip" from_work_dir="out_zip.zip"/>
        <data label="File tree (testing only)" name="file_tree" format="txt" from_work_dir="tree.txt" hidden="true">
            <filter>(testing == "true")</filter>
        </data>
    </outputs>
    <tests>
        <!-- CASTEP with out_folder and castep_param specified, param as txt -->
        <test expect_num_outputs="2">
            <param name="structure" value="Si.cell" ftype="cell"/>
            <param name="testing" value="true"/>
            <param name="params" value="configcastep_t_with_out_folder_and_castep_param.yaml" ftype="yaml"/>
            <conditional name="iscastep">
                <param name="iscastep_sel" value="true"/>
                <param name="castep_param" value="Si.param" ftype="txt"/>
            </conditional>
            <output name="file_tree" file="tree_castep_t_with_out_folder_and_castep_param.txt" ftype="txt" sort="true" />
        </test>
        <!-- CASTEP with out_folder and castep_param specified, param as yaml -->
        <test expect_num_outputs="2">
            <param name="structure" value="Si.cell" ftype="cell"/>
            <param name="testing" value="true"/>
            <param name="params" value="configcastep_t_with_out_folder_and_castep_param.yaml" ftype="yaml"/>
            <conditional name="iscastep">
                <param name="iscastep_sel" value="true"/>
                <param name="castep_param" value="Si.param" ftype="yaml"/>
            </conditional>
            <output name="file_tree" file="tree_castep_t_with_out_folder_and_castep_param.txt" ftype="txt" sort="true" />
        </test>
        <!-- CASTEP with no out_folder and no castep_param specified in yaml file -->
        <test expect_num_outputs="2">
            <param name="structure" value="Si.cell" ftype="cell"/>
            <param name="testing" value="true"/>
            <param name="params" value="configcastep_t_no_out_folder_no_castep_param.yaml" ftype="yaml"/>
            <conditional name="iscastep">
                <param name="iscastep_sel" value="true"/>
                <param name="castep_param" value="Si.param"/>
            </conditional>
            <output name="file_tree" file="tree_castep_t_no_outfolder_and_castep_param.txt" ftype="txt" sort="true" />
        </test>
        <!-- DFTB+ -->
        <test expect_num_outputs="2">
            <param name="structure" value="Si.cell" ftype="cell"/>
            <param name="testing" value="true"/>
            <param name="params" value="configdftb_t.yaml" ftype="yaml"/>
            <output name="file_tree" file="tree_dftb.txt" ftype="txt" sort="true" />
        </test>
        <!-- UEP with CELL -->
        <test expect_num_outputs="2">
            <param name="structure" value="Si.cell" ftype="cell"/>
            <param name="testing" value="true"/>
            <param name="params" value="configuep_t.yaml" ftype="yaml"/>
            <output name="file_tree" file="tree_uep.txt" ftype="txt" sort="true">
                <assert_contents>
                    <has_size value="734"/>
                </assert_contents>
            </output>
        </test>
        <!-- UEP with XYZ -->
        <test expect_failure="true">
            <param name="structure" value="Si.xyz" ftype="xyz"/>
            <param name="testing" value="true"/>
            <param name="params" value="configuep_t.yaml" ftype="yaml"/>
            <assert_stderr>
                <has_text text="TypeError: cannot unpack non-iterable NoneType object"/>
            </assert_stderr>
        </test>
        <!-- UEP with extended XYZ -->
        <test expect_num_outputs="2">
            <param name="structure" value="Si.extxyz" ftype="extxyz"/>
            <param name="testing" value="true"/>
            <param name="params" value="configuep_t.yaml" ftype="yaml"/>
            <output name="file_tree" file="tree_uep.txt" ftype="txt" sort="true">
                <assert_contents>
                    <has_size value="734"/>
                </assert_contents>
            </output>
        </test>
        <!-- UEP with CIF -->
        <test expect_num_outputs="2">
            <param name="structure" value="Si.cif" ftype="cif"/>
            <param name="testing" value="true"/>
            <param name="params" value="configuep_t.yaml" ftype="yaml"/>
            <output name="file_tree" file="tree_uep.txt" ftype="txt" sort="true">
                <assert_contents>
                    <has_size value="734"/>
                </assert_contents>
            </output>
        </test>
        <!-- check that file_tree filter works -->
        <test expect_num_outputs="1">
            <param name="structure" value="Si.cell" ftype="cell"/>
            <param name="testing" value="false"/>
            <param name="params" value="configuep_t.yaml" ftype="yaml"/>
        </test>
    </tests>
    <help><![CDATA[
        Given an input structure, this tool generates a set of duplicate structures, each with a single muon added in a random location. These are known as "muonated" structures.

        The YAML file controls many factors of the structure generation. We recommend using the '`YAML config generator`_' tool to create the file, but you can also write and upload it yourself following the `pm-muairss documentation`_.

        The resulting structures will be returned as a zip folder. This zip folder can be used as input for the '`Generate UEP outputs`_' tool, or downloaded for use outside Galaxy.

        Command-line usage: pm-muairss -t w structure_file parameter_file

        .. _pm-muairss documentation: https://github.com/muon-spectroscopy-computational-project/pymuon-suite/blob/master/docs/muairss-gen-docs.md
        .. _YAML config generator: /tool_runner?tool_id=pm_yaml_config
        .. _Generate UEP outputs: /tool_runner?tool_id=pm_uep_opt_write
    ]]></help>
    <citations>
        <citation type="bibtex">
            @misc{github,
                author = {{Muon Spectroscopy Computational Project}},
                year = {2021},
                title = {pymuon-suite 0.2.0},
                publisher = {GitHub},
                url = {https://github.com/muon-spectroscopy-computational-project/pymuon-suite/}
            }
        </citation>
        <citation type="bibtex">
            @article{airss,
                author = {Liborio, L. and Sturniolo, S. and Jochym, D.},
                title = {Computational prediction of muon stopping sites using ab initio random structure searching (AIRSS)},
                journal = {The Journal of Chemical Physics},
                volume = {148},
                pages = {134114},
                year = {2018},
                doi={10.1063/1.5024450},
                URL={
                    https://doi.org/10.1063/1.5024450
                },
                eprint={
                    https://doi.org/10.1063/1.5024450
                }
            }
        </citation>
        <citation type="bibtex">
            @article{doi:10.1063/1.5085197,
                author = {Sturniolo,Simone  and Liborio,Leandro  and Jackson,Samuel },
                title = {Comparison between density functional theory and density functional tight binding approaches for finding the muon stopping site in organic molecular crystals},
                journal = {The Journal of Chemical Physics},
                volume = {150},
                number = {15},
                pages = {154301},
                year = {2019},
                doi = {10.1063/1.5085197},
                URL = {
                        https://doi.org/10.1063/1.5085197
                },
                eprint = {
                        https://doi.org/10.1063/1.5085197
                }
            }
        </citation>
        <citation type="bibtex">
            @article{doi:10.1063/5.0012381,
                author = {Sturniolo,Simone  and Liborio,Leandro },
                title = {Computational prediction of muon stopping sites: A novel take on the unperturbed electrostatic potential method},
                journal = {The Journal of Chemical Physics},
                volume = {153},
                number = {4},
                pages = {044111},
                year = {2020},
                doi = {10.1063/5.0012381},
                URL = {
                        https://doi.org/10.1063/5.0012381
                },
                eprint = {
                        https://doi.org/10.1063/5.0012381
                },
                abstract = { Finding the stopping site of the muon in a muon-spin relaxation experiment is one of the main problems of muon spectroscopy, and computational techniques that make use of quantum chemistry simulations can be of great help when looking for this stopping site. The most thorough approach would require the use of simulations, such as Density Functional Theory (DFT), to test and optimize multiple possible sites, accounting for the effect that the added muon has on its surroundings. However, this can be computationally expensive and sometimes unnecessary. Hence, in this work, we present a software implementation of the Unperturbed Electrostatic Potential (UEP) Method: an approach used for finding the muon stopping site in crystalline materials. The UEP method requires only one DFT calculation, necessary to compute the electronic density. This, in turn, is used to calculate the minima of the crystalline material’s electrostatic potential and the estimates of the muon stopping site, relying on the approximation that the muon’s presence does not significantly affect its surroundings. One of the main UEP’s assumptions is that the muon stopping site will be one of the crystalline material’s electrostatic potential minima. In this regard, we also propose some symmetry-based considerations about the properties of this crystalline material’s electrostatic potential, in particular, which sites are more likely to be its minima and why the unperturbed approximation may be sufficiently robust for them. We introduce the Python software package pymuon-suite and the various utilities it provides to facilitate these calculations, and finally, we demonstrate the effectiveness of the method with some chosen example systems. }
            }
        </citation>
        <citation type="bibtex">
            @TOOL_CITATION@
        </citation>
    </citations>
</tool>