Metadata-Version: 1.2
Name: ciftostr
Version: 0.1.0
Summary: A small utility to convert crystal structures in CIF format into TOPAS STR format.
Home-page: https://github.com/rowlesmr/ciftostr
Author: Matthew Rowles
Author-email: rowlesmr@gmail.com
License: Apache-2.0
Project-URL: Documentation, https://ciftostr.readthedocs.io/
Project-URL: Changelog, https://ciftostr.readthedocs.io/en/latest/changelog.html
Project-URL: Issue Tracker, https://github.com/rowlesmr/ciftostr/issues
Description: ========
        Overview
        ========
        
        
        
        This program converts an arbitrary number of CIF (Crystallographic Information Format) files, each containing an arbitrary number of crystal structures, into a number of individual STR files that are compatible with the Rietveld analysis software, TOPAS. 
        
        If the program is run with zero command line arguments, then a GUI is launched, otherwise it is command-line driven.
        
        * Free software: Apache Software License 2.0
        
        Installation
        ============
        
        To install the release version from PyPi::
        
            pip install ciftostr
        
        You can also install the in-development version with::
        
            pip install https://github.com/rowlesmr/ciftostr/archive/master.zip
        
        
        How to run
        ==========
        
        If you would like to run it in the command line, you need to provide some command-line arguments::
        
        	ciftostr *.cif
        	ciftostr C:\user\username\some\directory\name.cif D:\data\file.cif
        	ciftostr /nfs/an/disks/jj/home/dir/file.cif home/folder/nest/deeper/important.cif
        
        will convert all CIF files in the current directory or the two CIF files specifically - both Windows and Linux filepaths are accepter. The resulting STR files will be saved in the same path as their parent CIF file. Relative or absolute file paths can be used.
        
        To launch the GUI::
        
        	python ciftostr.pyz
        
        
        Bonus Windows executable behaviour: You can drag a CIF file onto the program icon, and it will convert the CIF for you.
        
        To see some other helpful information, try::
        
        	python ciftostr.pyz --help
        	python ciftostr.pyz --info
        
        
        jEdit integration
        =================
        
        `Link text <link URL>`_
        
        `John Evans <http://topas.dur.ac.uk>`_ has made available `a number of macros <http://topas.dur.ac.uk/topaswiki/doku.php?id=jedi>`_ for the text editor `jEdit <http://www.jedit.org/>`_ that make it integrate very well with TOPAS when operating in launch mode.
        
        As a part of these macros, there is the ability to insert CIF files in STR format. If you wish to use ``ciftostr`` to generate the STR information, then you need to make the following changes:
        
        0. ``pip install ciftostr`` (or use ``ciftostr.exe``)
        1. Replace your copy of ``TAInsertCIF.bsh`` with `this one <TAInsertCIF.bsh>`_. (Your file is probably found in C:\\Users\\?????\\AppData\\Roaming\\jEdit\\macros)
        
        Now, when you choose "``Insert CIFs in INP format``" from the plugin in jEdit, ``ciftostr`` will be used in the background to generate that format.
        
        
        Documentation
        =============
        
        
        https://ciftostr.readthedocs.io/
        
        This program is designed to reformat data from a CIF format into the STR format suitable for use by the Rietveld analysis software, TOPAS. It doesn't carry out any validation checks to ensure the data is consistent, but simply transcribes the data as given in the CIF.
            
        Where similar or identical data could be given in several places, the values are taken in a specific order of precedence, as detailed in the sections below. In general, if a value exists in an earlier place, the later places are not looked at.
        
        This program uses the `PyCifRW <https://bitbucket.org/jamesrhester/pycifrw/src/development>`_ library, written by James Hester, to parse the CIF files into a format easily used to remix the underlying data. The GUI was created using `PySimpleGUI <https://pysimplegui.readthedocs.io/en/latest>`_. 
            
        The STR's phase_name is taken from ``_chemical_name_mineral``, ``_chemical_name_common``, ``_chemical_name_systematic``, or ``_chemical_name_structure_type``, in that order, appended with the value of the ``data`` block. If none of these keys are available, then the name of the ``data_`` block is used. This is also used as the filename of the STR file.
            
        The unit cell parameters are taken from ``_cell_length_a``, ``_cell_length_b``, ``_cell_length_c``, ``_cell_angle_alpha``, ``_cell_angle_beta``, and ``_cell_angle_gamma``. Some comparisons are made to enable some standard macros to be used (eg Cubic, Tetragonal...). In any of these fail, then all parameters are given as a fail safe.
        
        The space_group is taken from ``_symmetry_space_group_name_H-M``, ``_space_group_name_H-M_alt``, ``_symmetry_Int_Tables_number``, or ``_space_group_IT_number``, in that order. If none of these keys are available, then an empty string is written as the space group. The value of the space group is as exactly given in the CIF. No validation or editing is done.
        
        The atomic sites are constructed as follows: The atom labels are taken from ``_atom_site_label``, with the fractional x, y, and z coordinates given by ``_atom_site_fract_x``, ``_y``, and ``_z``. If the decimal values of the fractional coordinates are consistent with the fractions 1/6, 1/3, 2/3, or 5/6, then the decimal value is replaced by the fractions. The site occupancy is given by ``_atom_site_occupancy``, or by ``1``, if that key is not given. The atom type is given by ``_atom_site_type_symbol``, where available, or by the first one or two characters of the site label. If these characters match an element symbol, then that is used, otherwise, the label is used in it's entirety, and the user must decide the correct atom type to use. If the site label starts with ``Wat``, (and no atom type is given) it is assumed that oxygen (from water) is correct. An attempt is also made to reorder the charge given on an atom, to ensure it is compatible with TOPAS ordering, eg ``Fe+2``, not ``Fe2+``.
        
        Isotropic Atomic Displacement Parameters (ADPs; Biso), are taken from ``_atom_site_B_iso_or_equiv``, or from ``_atom_site_U_iso_or_equiv``, where they are then multiplied by 8*Pi^2 to give B values. If anisotropic ADPs are given, then ``_atom_site_aniso_B_11``, ``_atom_site_aniso_B_22``, and ``_atom_site_aniso_B_33`` are averaged to give an equivalent Biso value. Alternatively, the equivalent U values are used to calculate Biso. As anisotropic values could be given for a subset of the atoms in the structure, the labels given by ``_atom_site_label`` and ``_atom_site_aniso_label`` are matched, and if an atom doesn``t have an anisotropic value, it takes its isotropic value, or is assigned a value of ``1``.
        
        The atomic site is also given a ``num_posns 0`` entry, which will update with the multiplicity of the site following a refinement. This will allow the user to compare this value with the CIF or Vol A to help ensure that the correct symmetry is being applied.
        
        Finally, the STR is given a fixed Lorentzian crystallite size of 200 nm, and a refinable scale factor of 0.0001 to allow for an easy start to a refinement. All other values given in the STR are fixed, and require active intervention to name, refine, constrain, or restrain them.
        
        If you have any feedback, please contact me. If you find any bugs, please provide the CIF which caused the error, a description of the error, and a description of how you believe the program should work in that instance.
        
        
        Development
        ===========
        
        Come and talk to me!
        
        Changelog
        =========
        
        0.1.0 (2021-11-07)
        ------------------
        
        * It looks like everything is working!
        
        0.0.0 (2021-11-07)
        ------------------
        
        * First release on PyPI.
        
Keywords: diffraction,X-ray,neutron,synchrotron,powder diffraction,CIF,crystallography,Rietveld,TOPAS
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Utilities
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.6
