webmo 1.2.0__tar.gz → 1.3.3__tar.gz

{webmo-1.2.0/webmo.egg-info → webmo-1.3.3}/PKG-INFO

@@ -1,12 +1,15 @@
 Metadata-Version: 2.1
 Name: webmo
-Version: 1.2.0
+Version: 1.3.3
 Summary: A Python-based interface to WebMO
 Home-page: https://github.com/jrschmidt2/webmo-python
-Download-URL: https://github.com/jrschmidt2/webmo-python/archive/refs/tags/1.2.0.tar.gz
+Download-URL: https://github.com/jrschmidt2/webmo-python/archive/refs/tags/1.3.3.tar.gz
 Author: J.R. Schmidt
 Author-email: schmidt@webmo.net
 License: MIT
 Keywords: WEBMO,REST,API
 Provides-Extra: spectrum
+Provides-Extra: util
+Provides-Extra: gui
+Provides-Extra: all
 License-File: LICENSE

{webmo-1.2.0 → webmo-1.3.3}/setup.py

@@ -33,6 +33,9 @@ setup(
           'websockets',
   ],
   extras_require={
-      "spectrum": ["numpy"]
+      "spectrum": ["numpy"],
+      "util": ["PubChemPy"],
+      "gui": ["questionary", "ipywidgets"],
+      "all": ["numpy", "PubChemPy", "questionary", "ipywidgets"]
   }
 )

{webmo-1.2.0 → webmo-1.3.3}/webmo/__init__.py

@@ -1,2 +1,2 @@
 from .webmo_rest import WebMOREST
-__version__ = "1.2.0"
+__version__ = "1.3.3"

webmo-1.3.3/webmo/gui.py

@@ -0,0 +1,181 @@
+#handle abstract base class
+from abc import ABC, abstractmethod
+
+class _WebMOGUIBase(ABC):
+    """The _WebMOGUIBase class is an abstract base class for all Python-based GUIs for WebMO.
+    """
+
+    def __init__(self, template, query_vars, additional_vars):
+        self._query_vars = query_vars
+        self._additional_vars = additional_vars
+
+    @abstractmethod
+    def display(self):
+        """Presents the menu-driven JupyterGUI
+
+        Displays the JupyterGUI using a system of IPython widgets.
+
+        Args:
+            None
+
+        Returns:
+            None
+        """
+        pass
+
+    @abstractmethod
+    def get_variables(self):
+        """Returns a populated variables dictionary.
+
+        Returns a populated variables dictionary, generated using the user-selected
+        menu options, along with an additional user-specified key/value pairs (additional_vars)
+
+        Args:
+            None
+
+        Returns:
+            A populated dictionary of of variables and values.
+        """
+        pass
+
+class JupyterGUI(_WebMOGUIBase):
+    """The JupyterGUI class is a menu-driven Jupyter GUI interface for setting up WebMO jobs.
+
+    The class utilizes IPython widgets to present a menu-driven interface, using a subset
+    of user-specified list of template variables.
+    """
+    try:
+        import ipywidgets
+    except:
+        #fail silently, since this should never happen in Jupyter
+        pass #print('ipywidgets not found; disabling support for JupyterGUI')
+
+    def __init__(self, template, query_vars, additional_vars=None):
+        """Constructor for JupyterGUI
+
+        This constructor generates a JupyterGUI object.
+
+        Args:
+            template(dict): A specific template, selected from WebMOREST.get_templates()
+            query_vars(list): A subset of variables to use when generating the GUI
+            additional_vars(dict, optional): A dictionary of additional variables/values to utilize during input file generation
+
+        Returns:
+            object: The newly constructed JupyterGUI object
+        """
+
+        _WebMOGUIBase.__init__(self, template, query_vars, additional_vars)
+        self._widgets = []
+
+        for var in query_vars:
+            if template['variables'][var]['type'] == 'checkbox':
+                #handle checkbox options
+                self._widgets.append(
+                    self.ipywidgets.widgets.Checkbox(
+                        value=True if template['variables'][var]['default'] == 'on' else False,
+                        description=var,
+                        disabled=False));
+            elif template['variables'][var]['type'] == 'dropdown':
+                #handle select/dropdown options
+                self._widgets.append(
+                    self.ipywidgets.widgets.Dropdown(
+                        options=template['variables'][var]['options'],
+                        value=template['variables'][var]['default'],
+                        description=var,
+                        disabled=False));
+            else:
+                #handle text input
+                self._widgets.append(
+                    self.ipywidgets.widgets.Text(
+                        description=var,
+                        value=template['variables'][var]['default'],
+                        disabled=False));
+
+    def display(self):
+
+        for widget in self._widgets:
+            display(widget)
+
+    def get_variables(self):
+
+        # add in additional user-specified variables
+        if (self._additional_vars != None):
+            variables = {**self._additional_vars}
+        else:
+            variables = {}
+
+        for (var, widget) in zip(self._query_vars, self._widgets):
+            if isinstance(widget, self.ipywidgets.Checkbox):
+                variables[var] = "on" if widget.value == True else ""
+            else:
+                variables[var] = widget.value
+
+        return variables
+
+class ConsoleGUI(_WebMOGUIBase):
+    """The ConsoleGUI class is a text-based interface for setting up WebMO jobs.
+
+    The class utilizes the questionary library to present a neat interface using a subset
+    of user-specified list of template variables.
+    """
+
+    def __init__(self, template, query_vars, additional_vars=None):
+        """Constructor for ConsoleGUI
+
+        This constructor generates a ConsoleGUI object.
+
+        Args:
+            template(dict): A specific template, selected from WebMOREST.get_templates()
+            query_vars(list): A subset of variables to use when generating the GUI
+            additional_vars(dict, optional): A dictionary of additional variables/values to utilize during input file generation
+
+        Returns:
+            object: The newly constructed ConsoleGUI object
+        """
+
+        import questionary as q
+
+        _WebMOGUIBase.__init__(self, template, query_vars, additional_vars)
+        self._questions = []
+        for var in query_vars:
+            # checkbox options
+            if template['variables'][var]['type'] == 'checkbox':
+                self._questions.append(q.confirm(var));
+            # select/dropdown options
+            elif template['variables'][var]['type'] == 'dropdown':
+                choices = []
+                for key, value in template['variables'][var]['options'].items():
+                    choices.append(q.Choice(title=key, value=value))
+
+                self._questions.append(
+                    q.select(
+                        var,
+                        choices=choices,
+                        use_shortcuts=True));
+            # text input
+            else:
+                self._questions.append(
+                    q.text(var));
+
+
+    def display(self):
+
+        self._answers = []
+        for question in self._questions:
+            self._answers.append(question.ask())
+
+    def get_variables(self):
+
+        # add in additional user-specified variables
+        if (self._additional_vars != None):
+            variables = {**self._additional_vars}
+        else:
+            variables = {}
+
+        for (var, value) in zip(self._query_vars, self._answers):
+            if isinstance(value, bool):
+                variables[var] = "on" if value else ""
+            else:
+                variables[var] = value
+
+        return variables

webmo-1.3.3/webmo/util.py

@@ -0,0 +1,25 @@
+def xyz_from_name(name):
+    """Obtains an XYZ-formatted geometry for the molecule name via PubChem lookup.
+
+    Arguments:
+        name(str): The name of the molecule.
+
+    Returns:
+        A string containing the molecule's XYZ-formatted geometry.
+    """
+    import pubchempy as pcp
+
+    results = pcp.get_compounds(name, 'name', record_type='3d')
+    if (len(results) == 0):
+        raise ValueError("Specified molecule could not be found in PubChem")
+
+    record = results[0]
+    geom = ""
+    for atom in record.atoms:
+        element = atom.element
+        x = float(atom.x)
+        y = float(atom.y)
+        z = float(atom.z)
+        geom += f"{element}\t{x:f}\t{y:f}\t{z:f}\n"
+        
+    return geom

{webmo-1.2.0 → webmo-1.3.3}/webmo/webmo_rest.py

@@ -16,7 +16,7 @@ class WebMOREST:
     creation/destruction.
     """
     
-    def __init__(self, base_url, username, password=""):
+    def __init__(self, base_url, username, password="", expiration=24):
         """Constructor for WebMOREST
         
         This constructor generates a WebMOREST object and also generates and stores a newly
@@ -26,6 +26,7 @@ class WebMOREST:
             base_url(str): The base URL (ending in rest.cgi) of the WeBMO rest endpoint
             username(str): The WebMO username
             password(str, optional): The WebMO password; if omitted, this is supplied interactively
+            expiration(int, optional): The expiration time (in hours) of the REST session token
             
         Returns:
             object: The newly constructed WebMO object
@@ -36,7 +37,7 @@ class WebMOREST:
         if not password:
             password=getpass(prompt="Enter WebMO password for user %s:" % username)
         #obtain a REST token using the specified credentials
-        login={'username' : username, 'password' : password} #WebMO login information, used to retrieve a REST access token
+        login={'username' : username, 'password' : password, 'expiration' : expiration}
         r = requests.post(base_url + '/sessions', data=login)
         r.raise_for_status() #raise an exception if there is a problem with the request
         
@@ -52,8 +53,9 @@ class WebMOREST:
         
         This destructor automatically deletes the session token using the REST interface
         """
-        #End the REST sessions
-        r = requests.delete(self._base_url + '/sessions', params=self._auth)
+        #End the REST sessions; check in case requests has already been released
+        if requests.delete is not None:
+            r = requests.delete(self._base_url + '/sessions', params=self._auth)
         #do not raise an exception for a failed request in this case due to issues
         #with object management in Jupyter (i.e. on code re-run, a new token is made
         #prior to deletion!)
@@ -147,7 +149,7 @@ class WebMOREST:
             A list of folders
         """
         
-        #append other relevant paramters
+        #append other relevant parameters
         params = self._auth.copy()
         params.update({'user' : target_user})
         r = requests.get(self._base_url + "/folders", params=params)
@@ -195,21 +197,36 @@ class WebMOREST:
         r = requests.get(self._base_url + "/jobs/%d" % job_number, params=self._auth)
         r.raise_for_status()
         return r.json()
-        
-    def get_job_results(self, job_number):
-        """Returns detailed results of the calculation (e.g. energy, properties) from the specified job.
+
+    def _check_valid_job_list(self, job_numbers):
+        if len(job_numbers) == 0:
+            raise ValueError("One or more job number(s) must be specified")
+
+    def get_job_results(self, *job_numbers):
+        """Returns detailed results of the calculation (e.g. energy, properties) from the specified job(s).
         
         This call returns a JSON formatted string summarize all of the calculated and parsed properties
         from the specified job. This information is normally summarized on the View Job page.
         
         Arguments:
-            job_number(int): The job about whom to return information
+            *job_numbers(int): The job(s) for which to generate the results
             
         Returns:
             A JSON formatted string summarizing the calculated properties
         """
-        
-        r = requests.get(self._base_url + "/jobs/%d/results" % job_number, params=self._auth)
+
+        self._check_valid_job_list(job_numbers)
+
+        if (len(job_numbers) == 1):
+            #handle case of single job, return JSON dictionary for single job
+            r = requests.get(self._base_url + "/jobs/%d/results" % job_numbers[0], params=self._auth)
+        else:
+            #handle case of multiple jobs, return JSON array of dictionaries
+            #append other relevant parameters
+            params = self._auth.copy()
+            params.update({'jobNumber' : ",".join(str(job_number) for job_number in job_numbers)})
+            r = requests.get(self._base_url + "/jobs/results", params=params)
+
         r.raise_for_status()
         return r.json()
         
@@ -245,19 +262,45 @@ class WebMOREST:
         r.raise_for_status()
         return r.text
         
-    def get_job_archive(self, job_number):
-        """Returns a WebMO archive from the specified job.
+    def get_job_archive(self, *job_numbers):
+        """Returns a WebMO archive from the specified job(s).
         
-        This call generates and returns a binary WebMO archive (tar/zip) file from the specified job.
+        This call generates and returns a binary WebMO archive (tar/zip) file from the specified job(s).
         
         Arguments:
-            job_number(int): The job about whom to generate the archive
+            *job_numbers(int): The job(s) for which to generate the archive
             
         Returns:
             The raw data (as a string) of the WebMO archive, appropriate for saving to disk
         """
+
+        self._check_valid_job_list(job_numbers)
+
+        #append other relevant parameters
+        params = self._auth.copy()
+        params.update({'jobNumber' : ",".join(str(job_number) for job_number in job_numbers)})
+        r = requests.get(self._base_url + "/jobs/archive" % (), params=params)
+        r.raise_for_status()
+        return r.text
+        
+    def get_job_spreadsheet(self, *job_numbers):
+        """Returns a spreadsheet summary of the specified job(s).
+        
+        This call generates and returns a CSV-formatted spreadsheet summary of the specified job(s).
         
-        r = requests.get(self._base_url + "/jobs/%d/archive" % job_number, params=self._auth)
+        Arguments:
+            *job_numbers(int): The job(s) for which to generate the spreadsheet
+            
+        Returns:
+            The raw data (as a string) of the spreadsheet, appropriate for saving to disk
+        """
+
+        self._check_valid_job_list(job_numbers)
+
+        #append other relevant parameters
+        params = self._auth.copy()
+        params.update({'jobNumber' : ",".join(str(job_number) for job_number in job_numbers)})
+        r = requests.get(self._base_url + "/jobs/spreadsheet" % (), params=params)
         r.raise_for_status()
         return r.text
         
@@ -273,7 +316,7 @@ class WebMOREST:
         r = requests.delete(self._base_url + "/jobs/%d" % job_number, params=self._auth)
         r.raise_for_status()
         
-    def import_job(self, job_name, filename, engine):
+    def import_job(self, job_name, output_filename, engine):
         """Imports an existing output file into WebMO
         
         This call imports an existing computational output file, parsing the output and creating a newly
@@ -281,7 +324,7 @@ class WebMOREST:
         
         Arguments:
             job_name(str): The name of the new WebMO job
-            filename(str): The filename (full path) of an existing output file to import
+            output_filename(str): The filename (full path) of an existing output file to import
             engine(str): The name of the computational engine
             
         Returns:
@@ -290,31 +333,111 @@ class WebMOREST:
         
         params = self._auth.copy()
         params.update({'jobName' : job_name, 'engine' : engine})
-        output_file = {'outputFile' : ('output.log', open(filename, 'rb'), 'text/plain')}
+        output_file = {'outputFile' : ('output.log', open(output_filename, 'rb'), 'text/plain')}
         r = requests.post(self._base_url + '/jobs', data=params, files=output_file)
         r.raise_for_status()
         return r.json()["jobNumber"]
         
-    def submit_job(self, job_name, input_file_contents, engine, queue=None):
+    def submit_job(self, job_name, input_contents, engine, queue=None, nodes=1, ppn=1, **kwargs):
         """Submits and executes a new WebMO job
         
-        This call submits and executes a new job to a computational engine, generating a new WebMO job.
+        This call submits and executes a new job to a computational engine, generating a new WebMO job,
+        using nodes*ppn total cores.
         
         Arguments:
             job_name(str): The name of the new WebMO job
-            input_file_contents(str): The contents of a valid input file to submit to a computational engine
+            input_contents(str): The valid input for submission to the computational engine as its input file
             engine(str): The name of the computational engine
+            queue(str, optional): The name of the queue in which to submit the job_name (required for external queues)
+            nodes(int, optional): The number of nodes to use; defaults to 1
+            ppn(int, optional): The number of cores per node to use; defaults to 1
+            **kwargs(optional): Additional optional fields such as nodeType [PBS],
+            resourceList (aka constraints) [SGE/SLURM], timeLimit [SLURM], gpus [SLURM]
             
         Returns:
-            The the job number of the new job, upon success
+            The the job number of the new job, upon success.
         """
         
         params = self._auth.copy()
-        params.update({'jobName' : job_name, 'engine' : engine, 'inputFile': input_file_contents, 'queue': queue})
+        params.update({'jobName' : job_name, 'engine' : engine, 'inputFile': input_contents,
+            'queue': queue, 'nodes': nodes, 'ppn': ppn, **kwargs})
         r = requests.post(self._base_url + '/jobs', data=params)
         r.raise_for_status()
         return r.json()["jobNumber"]
         
+    #
+    # Template resource
+    #
+    def get_templates(self, engine):
+        """Fetches a list of job templates available to the current user
+
+        This call returns a dictionary of available templates and associated job variables.
+
+        Arguments:
+            engine(str): The name of the computational engine for which to fetch templates.
+
+        Returns:
+            A dictionary of available templates
+        """
+
+        r = requests.get(self._base_url + "/templates/%s" % engine, params=self._auth)
+        r.raise_for_status()
+        return r.json()["templates"]
+
+
+    def generate_input(self, template, variables, auto_defaults=True):
+        """Generates an input file from the specified template and dictionary of template job variables.
+
+        This call returns a text-formatted input file appropriate for submission.
+
+        Arguments:
+            template(dict): The desired job tempate (from get_templates)
+            variables(dict): A dictionary of variables to be used to generate the input file from the template.
+            auto_defaults(bool): Automatically use WebMO default values for omitted template variables
+
+        Returns:
+            A text-formatted input file
+        """
+        amend_variables = variables.copy()
+        if auto_defaults:
+            #update and amend 'variables' with default values for missing template parameters
+            for var in template['variables']:
+                if not var in variables:
+                    amend_variables[var] = template['variables'][var]['default']
+
+        #append other relevant paramters
+        params = self._auth.copy()
+        params.update({'variables' : json.dumps(amend_variables)})
+        r = requests.get(self._base_url + "/templates/%s" % template['id'], params=params)
+        r.raise_for_status()
+        return r.text
+
+    #
+    # Engines resource
+    #
+    def get_engines(self, target_user=""):
+        """Fetches a list of computational engines available to the current user or specified target user
+
+        This call returns a JSON-formatted list of available engines and associated queues.
+
+        Arguments:
+            target_user(str, optional): The target username whose folders are retrieved. Otherwise, uses the authenticated user.
+
+        Returns:
+            A JSON-formatted list of available engines, associated queues/servers, and
+            node and processor limits.
+        """
+
+        #append other relevant parameters
+        params = self._auth.copy()
+        params.update({'user' : target_user})
+        r = requests.get(self._base_url + "/engines", params=params)
+        r.raise_for_status()
+        return r.json()["engines"]
+
+    #
+    # Jupyter-related
+    #
     async def display_job_property(self, job_number, property_name, property_index=1, peak_width=0.0, tms_shift=0.0, proton_coupling=0.0, nmr_field=400.0, x_range=None, y_range=None, width=400, height=400, background_color=(255,255,255), transparent_background=False, rotate=(0.,0.,0.)):
         """Uses Javascript and IPython to display an image of the specified molecule and property,
         calculated from a previous WebMO job.
@@ -683,7 +806,7 @@ class WebMOREST:
 
     async def _process_callback_response(self):
         from base64 import b64decode
-        TIMEOUT = 10
+        TIMEOUT = 60
 
         json_msg = None
         for i in range(TIMEOUT):

{webmo-1.2.0 → webmo-1.3.3/webmo.egg-info}/PKG-INFO

@@ -1,12 +1,15 @@
 Metadata-Version: 2.1
 Name: webmo
-Version: 1.2.0
+Version: 1.3.3
 Summary: A Python-based interface to WebMO
 Home-page: https://github.com/jrschmidt2/webmo-python
-Download-URL: https://github.com/jrschmidt2/webmo-python/archive/refs/tags/1.2.0.tar.gz
+Download-URL: https://github.com/jrschmidt2/webmo-python/archive/refs/tags/1.3.3.tar.gz
 Author: J.R. Schmidt
 Author-email: schmidt@webmo.net
 License: MIT
 Keywords: WEBMO,REST,API
 Provides-Extra: spectrum
+Provides-Extra: util
+Provides-Extra: gui
+Provides-Extra: all
 License-File: LICENSE

{webmo-1.2.0 → webmo-1.3.3}/webmo.egg-info/SOURCES.txt

@@ -3,7 +3,9 @@ README.md
 setup.cfg
 setup.py
 webmo/__init__.py
+webmo/gui.py
 webmo/spectrum.py
+webmo/util.py
 webmo/webmo_rest.py
 webmo.egg-info/PKG-INFO
 webmo.egg-info/SOURCES.txt

webmo-1.3.3/webmo.egg-info/requires.txt

@@ -0,0 +1,18 @@
+requests
+websockets
+
+[all]
+numpy
+PubChemPy
+questionary
+ipywidgets
+
+[gui]
+questionary
+ipywidgets
+
+[spectrum]
+numpy
+
+[util]
+PubChemPy

webmo-1.2.0/webmo.egg-info/requires.txt

@@ -1,5 +0,0 @@
-requests
-websockets
-
-[spectrum]
-numpy