ncrystal-python 3.9.81__py3-none-any.whl

NCrystal/datasrc.py

@@ -0,0 +1,226 @@
+
+################################################################################
+##                                                                            ##
+##  This file is part of NCrystal (see https://mctools.github.io/ncrystal/)   ##
+##                                                                            ##
+##  Copyright 2015-2024 NCrystal developers                                   ##
+##                                                                            ##
+##  Licensed under the Apache License, Version 2.0 (the "License");           ##
+##  you may not use this file except in compliance with the License.          ##
+##  You may obtain a copy of the License at                                   ##
+##                                                                            ##
+##      http://www.apache.org/licenses/LICENSE-2.0                            ##
+##                                                                            ##
+##  Unless required by applicable law or agreed to in writing, software       ##
+##  distributed under the License is distributed on an "AS IS" BASIS,         ##
+##  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  ##
+##  See the License for the specific language governing permissions and       ##
+##  limitations under the License.                                            ##
+##                                                                            ##
+################################################################################
+
+"""
+
+Utilities for customising NCrystal's data sources, for instance by adding
+directories with data files to the search path, or adding in-memory files.
+
+"""
+
+from ._chooks import _get_raw_cfcts,_str2cstr
+import pathlib as _pathlib
+_rawfct = _get_raw_cfcts()
+
+def registerInMemoryFileData(virtual_filename,data):
+    """Register in-memory file data. This needs a "filename" and the content of this
+       virtual file. After registering such in-memory "files", they can be used
+       as file names in cfg strings or MatCfg objects. Registering the same
+       filename more than once, will simply override the content.
+
+       As a special case data can specified as "ondisk://<path>",
+       which will instead create a virtual alias for an on-disk file.
+
+       Technically, the registered file data will be delivered to users from a
+       factory named "virtual", so prefixing the filename with "virtual::" in
+       future requests, will guarantee that only data registered in this manner
+       is returned.
+    """
+    if ( isinstance(data,str) and data.startswith('ondisk://')):
+        data = 'ondisk://'+str(_pathlib.Path(data[9:]).resolve())
+    _rawfct['ncrystal_register_in_mem_file_data'](virtual_filename,data)
+
+
+def addCustomSearchDirectory(dirpath):
+    """Register custom directories to be monitored for data files."""
+    _rawfct['ncrystal_add_custom_search_dir'](_str2cstr(str(_pathlib.Path(dirpath).resolve())))
+
+def removeCustomSearchDirectories():
+    """Remove all search directories added with addCustomSearchDirectory."""
+    _rawfct['ncrystal_remove_custom_search_dirs']()
+
+def removeAllDataSources():
+    """Disable all standard data sources, remove all TextData factories as well,
+       clear all registered virtual files and custom search directories. Finish
+       by calling global clearCaches function ("Ripley: I say we take off and
+       nuke the entire site from orbit. It's the only way to be sure.").
+    """
+    _rawfct['ncrystal_remove_all_data_sources']()
+
+def enableAbsolutePaths( enable = True ):
+    """Whether or not absolute file paths are allowed."""
+    _rawfct['ncrystal_enable_abspaths'](1 if enable else 0)
+
+def enableRelativePaths( enable = True ):
+    """Whether or not paths relative to current working directory are allowed."""
+    _rawfct['ncrystal_enable_relpaths'](1 if enable else 0)
+
+def enableStandardSearchPath( enable = True ):
+    """Whether or not the standard search path should be searched. This standard
+      search path is is by default searched *after* the standard data library,
+      and is built by concatenating entries in the NCRYSTAL_DATA_PATH
+      environment variables with entries in the compile time definition of the
+      same name (in that order). Note that by default the standard search path
+      is searched *after* the standard data library.
+    """
+    _rawfct['ncrystal_enable_stdsearchpath'](1 if enable else 0)
+
+def enableStandardDataLibrary( enable = True, dirpath_override = None ):
+    """Whether or not the standard data library shipped with NCrystal should be
+       searched.
+
+       Unless NCrystal is configured to have the standard data library embedded
+       into the binary at compilation time, the location (directory path) of the
+       standard data library is taken from the NCRYSTAL_DATADIR environment
+       variable. If the environment variable is not set, the location is taken
+       from the compile time definition of the same name. If neither is set, and
+       data was not embedded at compilation time, the standard data library will
+       be disabled by default and the location must be provided before it can be
+       enabled. In all cases, the location can be overridden if explicitly
+       provided by the user as the second parameter to this function.
+    """
+    import ctypes
+    d = _str2cstr(str(_pathlib.Path(dirpath_override).resolve())) if dirpath_override else ctypes.cast(None, ctypes.c_char_p)
+    _rawfct['ncrystal_enable_stddatalib'](1 if enable else 0, d)
+
+class FileListEntry:
+    """Entry in list returned by browseFiles."""
+    def __init__(self,*,name,source,factName,priority):
+        self.__n = name or None
+        self.__f = factName or None
+        self.__p = int(priority) if priority.isdigit() else priority
+        self.__s = source or None
+
+    @property
+    def name(self):
+        """The (possibly virtual) filename needed to select this entry"""
+        return self.__n
+
+    @property
+    def source(self):
+        """Description (such as the parent directory in case of on-disk files)"""
+        return self.__s
+
+    @property
+    def factName(self):
+        """Name of the factory delivering entry."""
+        return self.__f
+
+    @property
+    def priority(self):
+        """The priority value of the entry (important in case multiple factories
+        delivers content with the the same name). Can be 'Unable',
+        'OnlyOnExplicitRequest' or an integer priority value (entries with
+        higher values will be preferred).
+        """
+        return self.__p
+
+    @property
+    def fullKey(self):
+        """The string '%s::%s'%(self.factName,self.name), which can be used to
+           explicitly request this entry without interference from similarly
+           named entries in other factories.
+        """
+        return '%s::%s'%(self.__f,self.__n)
+
+    def __str__(self):
+        ll=[]
+        if self.__n:
+            ll+=['name=%s'%self.__n]
+        if self.__s:
+            ll+=['source=%s'%self.__s]
+        if self.__f:
+            ll+=['factory=%s'%self.__f]
+        ll+=['priority=%s'%self.__p]
+        return 'FileListEntry(%s)'%(', '.join(ll))
+
+    def __lt__(self, other):
+        if not isinstance(other, FileListEntry):
+            return False
+        return ( (self.__f,self.__n,self.__s,self.__p)
+                 < (other.__f,other.__n,other.__s,other.__p) )
+
+def browseFiles(dump=False,factory=None):
+    """Browse list of available input files (virtual or on-disk). The list is not
+       guaranteed to be exhaustive, but will usually include all files in
+       supported files in the most obvious locations (the NCrystal data
+       directory and other directories of the standard search path, the current
+       working directory, virtual files embedded in the NCrystal library or
+       registered dynamically.
+
+       Returns a list of FileListEntry objects. If the dump flag is set to True,
+       the list will also be printed to stdout in a human readable form.
+
+       Setting factory parameter will only return / print entries from the
+       factory of that name.
+
+    """
+    res=[]
+    def sortkey(e):
+        praw = e.priority
+        if praw=='Unable':
+            p=-2
+        elif isinstance(praw,int):
+            p=praw
+        else:
+            assert praw=='OnlyOnExplicitRequest'
+            p=-1
+        return (-p, e.factName,e.source,e.name)
+    for n,s,f,p in _rawfct['ncrystal_get_filelist']():
+        res.append( FileListEntry(name=n,source=s,factName=f,priority=p) )
+    res.sort(key=sortkey)
+    if dump:
+        seen_names=set()
+        def groupfct( e ):
+            return (e.factName,e.source,e.priority)
+        lastgroup = None
+        pending=[]
+        def print_pending():
+            if not pending:
+                return
+            if factory is not None and lastgroup[0]!=factory:
+                pending.clear()
+                return
+            n=len(pending) - 1
+            pending[0] = pending[0]%('%s files'%n if n!=1 else '%s file'%n )
+            for line in pending:
+                print (line)
+            pending.clear()
+        for e in res:
+            group = groupfct(e)
+            if lastgroup != group:
+                print_pending()
+                lastgroup = group
+                pending.append('==> %%s from "%s" (%s, priority=%s):'%group)
+            hidden = e.name in seen_names
+            seen_names.add(e.name)
+            extra=''
+            prname=e.name
+            if e.priority=='OnlyOnExplicitRequest':
+                prname='%s::%s'%(e.factName,e.name)
+            elif hidden:
+                extra=' <--- Hidden by higher priority entries (select as "%s::%s")'%(e.factName,e.name)
+            pending.append(    '    %s%s'%(prname,extra))
+        print_pending()
+        return #return None in this case, to avoid spurious printouts in an interactive session
+    if factory is None:
+        return res
+    return [e for e in res if e.factName==factory]

NCrystal/exceptions.py

@@ -0,0 +1,66 @@
+
+################################################################################
+##                                                                            ##
+##  This file is part of NCrystal (see https://mctools.github.io/ncrystal/)   ##
+##                                                                            ##
+##  Copyright 2015-2024 NCrystal developers                                   ##
+##                                                                            ##
+##  Licensed under the Apache License, Version 2.0 (the "License");           ##
+##  you may not use this file except in compliance with the License.          ##
+##  You may obtain a copy of the License at                                   ##
+##                                                                            ##
+##      http://www.apache.org/licenses/LICENSE-2.0                            ##
+##                                                                            ##
+##  Unless required by applicable law or agreed to in writing, software       ##
+##  distributed under the License is distributed on an "AS IS" BASIS,         ##
+##  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  ##
+##  See the License for the specific language governing permissions and       ##
+##  limitations under the License.                                            ##
+##                                                                            ##
+################################################################################
+
+"""Module defining all the exception and warning types emitted by NCrystal"""
+
+#NB: We also put all of these in __all__ in the main __init__.py:
+
+__all__ = [ 'NCrystalUserWarning',
+            'NCException',
+            'NCFileNotFound',
+            'NCDataLoadError',
+            'NCMissingInfo',
+            'NCCalcError',
+            'NCLogicError',
+            'NCBadInput',
+            'nc_assert' ]
+
+class NCrystalUserWarning( UserWarning ):
+    """UserWarning's emitted from NCrystal code"""
+    def __init__(self,*args,**kwargs):
+        super(NCrystalUserWarning, self).__init__(*args,**kwargs)
+
+class NCException(RuntimeError):
+    """Base class for all exceptions raised by NCrystal code"""
+    pass
+
+class NCFileNotFound(NCException):
+    pass
+
+class NCDataLoadError(NCException):
+    pass
+
+class NCMissingInfo(NCException):
+    pass
+
+class NCCalcError(NCException):
+    pass
+
+class NCLogicError(NCException):
+    pass
+
+class NCBadInput(NCException):
+    pass
+
+def nc_assert(b,msg=""):
+    """Assertion which throws NCLogicError on failure"""
+    if not bool(b):
+        raise NCLogicError(msg if msg else 'assertion failed')

NCrystal/hfg2ncmat.py

@@ -0,0 +1,270 @@
+
+################################################################################
+##                                                                            ##
+##  This file is part of NCrystal (see https://mctools.github.io/ncrystal/)   ##
+##                                                                            ##
+##  Copyright 2015-2024 NCrystal developers                                   ##
+##                                                                            ##
+##  Licensed under the Apache License, Version 2.0 (the "License");           ##
+##  you may not use this file except in compliance with the License.          ##
+##  You may obtain a copy of the License at                                   ##
+##                                                                            ##
+##      http://www.apache.org/licenses/LICENSE-2.0                            ##
+##                                                                            ##
+##  Unless required by applicable law or agreed to in writing, software       ##
+##  distributed under the License is distributed on an "AS IS" BASIS,         ##
+##  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  ##
+##  See the License for the specific language governing permissions and       ##
+##  limitations under the License.                                            ##
+##                                                                            ##
+################################################################################
+
+"""
+
+Utilities for generating NCMAT files for hydrogen rich amorphous materials
+(based on doi:10.1088/1361-648X/abfc13).
+
+"""
+
+__all__ = [ 'hfg2ncmat']
+
+def _default_debye_temp():
+    #Note: keep in synch with value mentioned in docstring of hfg2ncmat
+    #function, as well as the NCMATComposer.from_hfg method.
+    return 400.0
+
+def _parseChemicalFormula(chemform):
+    import re
+    def err():
+        from .exceptions import NCBadInput
+        raise NCBadInput(f'Invalid chemical formula: "{chemform}"')
+    def is_ascii(s):
+        #str.isascii requires python 3.7
+        return all(ord(c) < 128 for c in s)
+    if not is_ascii(chemform) or not chemform.isalnum():
+        err()
+    d={}
+    prev=None
+    def add(element,count):
+        d[element] = d.get(element,0) + count
+
+    chemform_unused = chemform.strip()
+    for e in re.findall('[A-Z][a-z]?|[0-9]+', chemform.strip()):
+        if chemform_unused.startswith(e):
+            chemform_unused = chemform_unused[len(e):].strip()
+        else:
+            err()
+        if e.isdigit():
+            if prev is None or prev.isdigit():
+                err()
+            v=int(e)
+            if v<1 or v>1000000000:
+                err()
+            add(prev,v)
+            prev=None
+            continue
+        if prev is not None:
+            add(prev,1)
+            prev = None
+        prev = e
+    if prev is not None:
+        add(prev,1)
+    if chemform_unused:
+        err()
+    return d
+
+def _parseHydrogenBindingSpecification(spec):
+    from .exceptions import NCBadInput
+    def err():
+        raise NCBadInput(f'Invalid hydrogen binding specification: "{spec}"')
+    def is_ascii(s):
+        #str.isascii requires python 3.7
+        return all(ord(c) < 128 for c in s)
+    if not is_ascii(spec) or not spec.replace('+','').isalnum():
+        err()
+
+    fg2nH=dict(CHali=1,CHaro=1,CH2=2,CH3=3,NH=1,NH2=2,NH3=3,OH=1,SH=1)
+    d={}
+    for part in spec.split('+'):
+        p=part.strip().split('x')
+        if len(p)!=2:
+            err()
+        count,fg=p
+        if fg not in fg2nH:
+            raise NCBadInput(f'Unknown functional group in "{spec}": "{fg}"')
+        if not count.isdigit() or not 1 <= int(count) <= 10000:
+            raise NCBadInput(f'Invalid count in "{spec}": "{count}"')
+        d[fg] = d.get(fg,0)+int(count)*fg2nH[fg]
+    return d
+
+def hfg2ncmat( spec,
+               formula, *,
+               density,
+               title,
+               debyetemp = _default_debye_temp(),
+               verbose = True,
+               notrim = False ):
+    """Function which can be used to generate NCMAT data for hydrogen-rich
+amorphous materials, in which the hydrogen atoms are bound to certain standard
+functional groups (e.g. carbohydrates, polyimides, polymers, ...). Based on the
+material's density, (empirical) chemical formula, and the specification of
+hydrogen bindings in terms of standard functional groups, NCMAT data is
+generated. In this NCMAT data, non-hydrogen atoms are treated with a simplistic
+model (idealised Debye model of phonon vibrations, assuming a Debye temperature
+of 400K for all atoms unless the debyetemp parameter is provided. The hydrogen
+atoms are treated with a proper phonon density of state (VDOS) curve, which is
+constructed based on the provided binding specifications. This is done using an
+idea (and VDOS curves from) the following publication:
+
+  "Thermal neutron cross sections of amino acids from average contributions
+  of functional groups", G. Romanelli, et. al., J. Phys.: Condens. Matter,
+  (2021). doi:10.1088/1361-648X/abfc13
+
+Example of valid spec strings for the spec parameter. Note only the hydrogen
+bindings are important here:
+
+     "1xCHali+2xCH2+8xCHaro+2xCH3+1xOH" (20 hydrogen atoms)
+     "1xNH+3xSH+2xCH2" (8 hydrogen atoms).
+
+List of valid bindings which can be used in the spec string:
+
+      CHali (1 hydrogen atom, aliphatic binding)
+      CHaro (1 hydrogen atom, aromatic binding, e.g. on phenyl group).
+      CH2 (2 hydrogen atoms)
+      CH3 (3 hydrogen atoms)
+      NH (1 hydrogen atom)
+      NH2 (2 hydrogen atoms)
+      NH3 (3 hydrogen atoms)
+      OH (1 hydrogen atom)
+      SH (1 hydrogen atom)
+
+Note that as only hydrogen atoms will have a realistic VDOS curve, and as the
+incoherent approximation is employed, the realism of the resulting material
+modelling will be higher for materials with more hydrogen atoms. As a metric of
+this, the function prints out how much of the total scattering cross section
+(sum of sigma_coh+sigma_incoh for all atoms), is due to the sigma_incoh
+contribution from hydrogen atoms (unless verbose=False).
+
+"""
+    #NOTE: Keep the description above synchronised with help text of of the
+    #ncrystal_hfg2ncmat command-line app!
+
+    from ._hfgdata import get_data as hfg_get_data
+
+    if verbose:
+        from ._common import print
+    else:
+        def print(*args,**kwargs):
+            pass
+
+    spec_parsed = _parseHydrogenBindingSpecification(spec)
+    chemform = _parseChemicalFormula(formula)
+
+    nH = chemform.get('H',-999)
+    if sum(v for k,v in spec_parsed.items()) != nH:
+        from .exceptions import NCBadInput
+        raise NCBadInput('number of hydrogen items in --formula'
+                         ' and --spec does not match up.')
+
+    egrid,vdos = hfg_get_data()
+
+    #Calculate hydrogen VDOS:
+
+    h_vdos = sum( nh * vdos[fgname] for fgname,nh in sorted(spec_parsed.items()))
+    h_vdos /= h_vdos.max()
+
+    debye_cut_bin = 4#shave off first few points, to force parabolic behaviour near E=0.
+    if not notrim:
+        for i in range(len(h_vdos)):
+            if egrid[i]<0.05:
+                continue#don't touch first bins
+            if h_vdos[i]<1e-7:
+                h_vdos[i]=0.0
+        ntrim=2
+        assert debye_cut_bin%ntrim==0
+        debye_cut_bin //= ntrim
+        h_vdos = h_vdos[::ntrim]
+        egrid = egrid[::ntrim]
+
+    while len(h_vdos)>10 and h_vdos[-2]==0.0 and h_vdos[-1]==0.0:
+        h_vdos = h_vdos[0:-1]
+        egrid = egrid[0:-1]
+
+    appname='ncrystal_hfg2ncmat'
+
+    initial_comments='#\n'
+    for ll in title.replace('\\n','\n').splitlines():
+        initial_comments+= f'# {ll}\n' if ll.strip() else '#\n'
+    initial_comments+='#'
+
+    recordargs=[ f'--spec={spec}',
+                 f'--formula={formula}',
+                 f'--density={density}' ]
+    if _default_debye_temp() != debyetemp:
+        recordargs.append('--debyetemp=%.14g'%debyetemp)
+    if notrim:
+        recordargs.append('--notrim')
+    recordargs='\n#  '.join(recordargs)
+
+    out = f"""NCMAT v5
+{initial_comments}
+# ----------------------------------------------------------------------------
+#
+# File generated by {appname} with:
+#
+#  {recordargs}
+#
+# The hydrogen VDOS curve in this file is constructed using data from:
+#
+#   "Thermal neutron cross sections of amino acids from average contributions
+#   of functional groups", G. Romanelli, et. al., J. Phys.: Condens. Matter,
+#   (2021). doi:10.1088/1361-648X/abfc13
+#
+# Considering only scat. lengths and composition, incoherent scattering on
+# hydrogen accounts for <<<HYDROGENPERCENTAGE>>> of scattering in this material (a higher value
+# implies more accurate modelling).
+#
+@STATEOFMATTER
+  solid
+@DENSITY
+  {density} g_per_cm3
+"""
+
+    ntot = sum(n for elem,n in chemform.items())
+    for elem,n in chemform.items():
+        if elem=='H':
+            continue
+        out+=f"""@DYNINFO
+  element {elem}
+  fraction {n}/{ntot}
+  type vdosdebye
+  debye_temp {debyetemp}
+"""
+    out+=f"""@DYNINFO
+  element  H
+  fraction {nH}/{ntot}
+  type     vdos
+  vdos_egrid {0.001*egrid[debye_cut_bin]:.8g} {0.001*egrid[-1]:.8g}
+"""
+    from .ncmat import formatVectorForNCMAT
+    out += formatVectorForNCMAT('vdos_density',h_vdos[debye_cut_bin:])
+    print ("Generated NCMAT data...")
+    print ("Verifying that it can be loaded with NCrystal...")
+    from .core import load as nc_load
+    loaded_mat = nc_load(out)
+    print ("Succesfully loaded...")
+
+    breakdown = []
+    for di in loaded_mat.info.dyninfos:
+        for cohtype in 'incoherent','coherent':
+            key='%s (%s)'%(di.atomData.displayLabel(),cohtype)
+            sigma = di.atomData.coherentXS() if cohtype=='coherent' else di.atomData.incoherentXS()
+            breakdown+=[(di.fraction*sigma,key)]
+    sigma_tot = sum(s for s,k in breakdown)
+    print("Contribution breakdown based on composition:")
+    for s,key in reversed(sorted(breakdown)):
+        print ("  Contribution to bound scattering XS from %s is %5.2f %%"%(key.ljust(14),s*100.0/sigma_tot))
+        if key=='H (incoherent)':
+            contrib_incH = s/sigma_tot
+
+    return out.replace('<<<HYDROGENPERCENTAGE>>>','%.3g%%'%(100.0*contrib_incH))