annotate pm_uep_opt.xml @ 0:e4097a3e3e75 draft

planemo upload for repository https://github.com/muon-spectroscopy-computational-project/muon-galaxy-tools/main/pm_uep_opt commit d130cf2c46d933fa9d0214ddbd5ddf860f322dc4

<tool id="pm_uep_opt" name="PyMuonSuite AIRSS UEP Optimise" version="@TOOL_VERSION@+galaxy@WRAPPER_VERSION@" python_template_version="3.5" profile="22.01">
    <description>run UEP optimisation</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="Jyothish" familyName="Thomas" identifier="https://orcid.org/0000-0003-4724-6924"/>
        <person givenName="Eli" familyName="Chadwick" url="https://github.com/elichad" identifier="https://orcid.org/0000-0002-0035-6475"/>
        <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>
    <command detect_errors="exit_code"><![CDATA[
        unzip "$muonated_structures" &&
        if test -f "params.yaml"; then echo "params.yaml present"; else echo "params.yaml missing" && exit 64; fi &&
        if ( test -f input_structure.* ) ; then echo "input structure present"; else echo "input structure missing" && exit 64; fi &&
        charge_density_name=\$(sed 's/ //g' <<< "$charge_density.name") &&
        ln -s $charge_density \$charge_density_name &&
        x="\$charge_density_name" &&
        echo "calculated seed name \$x" &&
        ln -s $castep_log "\${x%%.*}.castep" &&
        out_folder="`python ${__tool_directory__}/get_out_folder.py`" &&
        find \$out_folder -type f -name "*.yaml" | xargs sed -i "s#^chden_path: .*#chden_path: .\/#g" &&
        find \$out_folder -type f -name "*.yaml" | xargs sed -i "s#^chden_seed: .*#chden_seed: \${x%%.*}#g" &&
        bash ${__tool_directory__}/run.sh \$out_folder &&
        zip -r out_zip.zip \$out_folder params.yaml input_structure.* &&
        find \$out_folder > tree.txt
    ]]></command>
    <inputs>
        <param type="data" name="muonated_structures" label="Muonated structures (.zip)" format="zip" help="A zip folder containing muonated structures, as generated by the 'Generate muonated structures' tool or pm-muairss."/>
        <param type="data" name="charge_density" label="Charge density file (.den_fmt)" format="txt" help="The charge density file created by CASTEP during your initial DFT simulation for the structure."/>
        <param type="data" name="castep_log" label="CASTEP log (.castep)" format="txt" help="The CASTEP log for your initial DFT simulation for the structure."/>
        <param type="hidden" name="testing" label="Test mode" value="false"/>
    </inputs>
    <outputs>
        <data label="UEP results for $muonated_structures.name" name="uep_results" 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>
        <test>
            <param name="testing" value="true"/>
            <param name="muonated_structures" value="muonated.zip" ftype="zip"/>
            <param name="charge_density" value="Si.den_fmt" ftype="txt"/>
            <param name="castep_log" value="Si.castep" ftype="txt"/>
            <output name="file_tree" file="tree.txt" ftype="txt" sort="true">
                <assert_contents>
                    <has_size value="1780"/>
                </assert_contents>
            </output>
        </test>
        <test expect_num_outputs="2">
            <param name="testing" value="true"/>
            <param name="muonated_structures" value="muonated-default-folder.zip" ftype="zip"/>
            <param name="charge_density" value="Si.den_fmt" ftype="txt"/>
            <param name="castep_log" value="Si.castep" ftype="txt"/>
            <output name="file_tree" file="tree-default-folder.txt" sort="true"/>
        </test>
        <test expect_failure="true">
            <param name="testing" value="true"/>
            <param name="muonated_structures" value="muonated-default-folder.zip" ftype="zip"/>
            <param name="castep_log" value="Si.castep" ftype="txt"/>
            <param name="charge_density" value="Sifail.den_fmt" ftype="txt"/>
            <assert_stderr>
                <has_text text="Error:  FMT file has no header"/>
            </assert_stderr>
        </test>
        <!-- check that file_tree filter works -->
        <test expect_num_outputs="1">
            <param name="testing" value="false"/>
            <param name="muonated_structures" value="muonated.zip" ftype="zip"/>
            <param name="charge_density" value="Si.den_fmt" ftype="txt"/>
            <param name="castep_log" value="Si.castep" ftype="txt"/>
        </test>
    </tests>
    <help><![CDATA[
        Given a set of input muonated structures (structures containing a muon), applies UEP optimisation to refine them.

        This tool requires CASTEP inputs for the UEP method, meaning your initial DFT simulation must have been done with CASTEP.
        The structure you used as input to the '`Generate muonated structures`_' tool or pm-muairss beforehand should come from the same simulation run.

        Command-line usage: pm-uep-opt [-h] [-t {r,w}] structures parameter_file

        .. _Generate muonated structures: /tool_runner?tool_id=pm_muairss_write
    ]]></help>
    <citations>
        <citation type="bibtex">
            @TOOL_CITATION@
        </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 optimise 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">
            @article {castep,
                author = {Clark, S. J. and Segall, M. D. and Pickard, C. J. and Hasnip, P. J. and Probert, M. I. J. and Refson, K. and Payne, M. C.},
                title = {First principles methods using CASTEP},
                journal = {Zeitschrift fuer Kristallographie},
                volume = {220},
                pages = {567},
                year = {2005}
            }
        </citation>
    </citations>
</tool>