aiida-pythonjob 0.1.7__tar.gz → 0.2.0__tar.gz

{aiida_pythonjob-0.1.7 → aiida_pythonjob-0.2.0}/.gitignore

@@ -70,6 +70,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/autogen/
+docs/source/sg_execution_times.rst
 
 # PyBuilder
 .pybuilder/

{aiida_pythonjob-0.1.7 → aiida_pythonjob-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiida-pythonjob
-Version: 0.1.7
+Version: 0.2.0
 Summary: Run Python functions on a remote computer.
 Project-URL: Source, https://github.com/aiidateam/aiida-pythonjob
 Author-email: Xing Wang <xingwang1991@gmail.com>
@@ -37,7 +37,8 @@ Requires-Python: >=3.9
 Requires-Dist: aiida-core<3,>=2.3
 Requires-Dist: ase
 Requires-Dist: cloudpickle
-Requires-Dist: voluptuous
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: furo; extra == 'docs'
 Requires-Dist: markupsafe<2.1; extra == 'docs'

aiida_pythonjob-0.2.0/docs/gallery/autogen/pyfunction.py

@@ -0,0 +1,191 @@
+"""
+PyFunction
+===============
+
+"""
+
+######################################################################
+# Default outputs
+# --------------
+#
+# The default output of the function is `result`. The `pyfunction` task
+# will store the result as one node in the database with the key `result`.
+#
+from aiida import load_profile
+from aiida.engine import run_get_node
+from aiida_pythonjob import pyfunction
+
+load_profile()
+
+
+@pyfunction()
+def add(x, y):
+    return x + y
+
+
+result, node = run_get_node(add, x=1, y=2)
+print("result: ", result)
+
+######################################################################
+# Custom outputs
+# --------------
+# If the function return a dictionary with fixed number of keys, and you
+# want to store the values as separate outputs, you can specify the `function_outputs` parameter.
+# For a dynamic number of outputs, you can use the namespace output, which is explained later.
+#
+
+
+@pyfunction(outputs=[{"name": "sum"}, {"name": "diff"}])
+def add(x, y):
+    return {"sum": x + y, "diff": x - y}
+
+
+result, node = run_get_node(add, x=1, y=2)
+
+print("result: ")
+print("sum: ", result["sum"])
+print("diff: ", result["diff"])
+
+######################################################################
+# Namespace Output
+# --------------
+#
+# The `pyfunction` allows users to define namespace outputs. A namespace output
+# is a dictionary with keys and values returned by a function. Each value in
+# this dictionary will be serialized to AiiDA data, and the key-value pair
+# will be stored in the database.
+#
+# Why Use Namespace Outputs?
+#
+# - **Dynamic and Flexible**: The keys and values in the namespace output are not fixed and can change based on the task's execution. # noqa
+# - **Querying**: The data in the namespace output is stored as an AiiDA data node, allowing for easy querying and retrieval. # noqa
+# - **Data Provenance**: When the data is used as input for subsequent tasks, the origin of data is tracked.
+#
+# For example: Consider a molecule adsorption calculation where the namespace
+# output stores the surface slabs of the molecule adsorbed on different surface
+# sites. The number of surface slabs can vary depending on the surface. These
+# output surface slabs can be utilized as input to the next task to calculate the energy.
+
+from ase import Atoms  # noqa: E402
+from ase.build import bulk  # noqa: E402
+
+
+@pyfunction(outputs=[{"name": "scaled_structures", "identifier": "namespace"}])
+def generate_structures(structure: Atoms, factor_lst: list) -> dict:
+    """Scale the structure by the given factor_lst."""
+    scaled_structures = {}
+    for i in range(len(factor_lst)):
+        atoms = structure.copy()
+        atoms.set_cell(atoms.cell * factor_lst[i], scale_atoms=True)
+        scaled_structures[f"s_{i}"] = atoms
+    return {"scaled_structures": scaled_structures}
+
+
+result, node = run_get_node(generate_structures, structure=bulk("Al"), factor_lst=[0.95, 1.0, 1.05])
+print("scaled_structures: ")
+for key, value in result["scaled_structures"].items():
+    print(key, value)
+
+
+######################################################################
+# Exit Code
+# --------------
+# Users can define custom exit codes to indicate the status of the task.
+#
+# When the function returns a dictionary with an `exit_code` key, the system
+# automatically parses and uses this code to indicate the task's status. In
+# the case of an error, the non-zero `exit_code` value helps identify the specific problem.
+#
+#
+
+
+@pyfunction()
+def add(x, y):
+    sum = x + y
+    if sum < 0:
+        exit_code = {"status": 410, "message": "Some elements are negative"}
+        return {"sum": sum, "exit_code": exit_code}
+    return {"sum": sum}
+
+
+result, node = run_get_node(add, x=1, y=-2)
+print("exit_status:", node.exit_status)
+print("exit_message:", node.exit_message)
+
+
+######################################################################
+# Define your data serializer and deserializer
+# --------------
+#
+# PythonJob search data serializer from the `aiida.data` entry point by the
+# module name and class name (e.g., `ase.atoms.Atoms`).
+#
+# In order to let the PythonJob find the serializer, you must register the
+# AiiDA data with the following format:
+#
+# .. code-block:: ini
+#
+#    [project.entry-points."aiida.data"]
+#    abc.ase.atoms.Atoms = "abc.xyz:MyAtomsData"
+#
+# This will register a data serializer for `ase.atoms.Atoms` data. `abc` is
+# the plugin name, the module name is `xyz`, and the AiiDA data class name is
+# `AtomsData`. Learn how to create an AiiDA data class `here <https://aiida.readthedocs.io/projects/aiida-core/en/stable/topics/data_types.html#adding-support-for-custom-data-types>`_.
+#
+# *Avoid duplicate data serializer*: If you have multiple plugins that
+# register the same data serializer, the PythonJob will raise an error.
+# You can avoid this by selecting the plugin that you want to use in the configuration file.
+#
+#
+# .. code-block:: json
+#
+#    {
+#        "serializers": {
+#            "ase.atoms.Atoms": "abc.ase.atoms.AtomsData" # use the full path to the serializer
+#        }
+#    }
+#
+# Save the configuration file as `pythonjob.json` in the aiida configuration
+# directory (by default, `~/.aiida` directory).
+#
+# If you want to pass AiiDA Data node as input, and the node does not have a `value` attribute,
+# then one must provide a deserializer for it.
+#
+
+from aiida import orm  # noqa: E402
+
+
+@pyfunction()
+def make_supercell(structure, n=2):
+    return structure * [n, n, n]
+
+
+structure = orm.StructureData(cell=[[1, 0, 0], [0, 1, 0], [0, 0, 1]])
+structure.append_atom(position=(0.0, 0.0, 0.0), symbols="Li")
+
+result, node = run_get_node(
+    make_supercell,
+    structure=structure,
+    deserializers={
+        "aiida.orm.nodes.data.structure.StructureData": "aiida_pythonjob.data.deserializer.structure_data_to_atoms"
+    },
+)
+print("result: ", result)
+
+######################################################################
+# One can also set the deserializer in the configuration file.
+#
+#
+# .. code-block:: json
+#
+#    {
+#        "serializers": {
+#            "ase.atoms.Atoms": "abc.ase.atoms.Atoms"
+#        },
+#        "deserializers": {
+#            "aiida.orm.nodes.data.structure.StructureData": "aiida_pythonjob.data.deserializer.structure_data_to_pymatgen" # noqa
+#        }
+#    }
+#
+# The `orm.List`, `orm.Dict`and `orm.StructureData` data types already have built-in deserializers.
+#

aiida_pythonjob-0.1.7/docs/gallery/autogen/how_to.py → aiida_pythonjob-0.2.0/docs/gallery/autogen/pythonjob.py

@@ -1,5 +1,5 @@
 """
-How to guides
+PythonJob
 ===============
 
 """
@@ -241,14 +241,12 @@ print("retrieved files: ", result["retrieved"].list_object_names())
 # is a dictionary with keys and values returned by a function. Each value in
 # this dictionary will be serialized to AiiDA data, and the key-value pair
 # will be stored in the database.
+#
 # Why Use Namespace Outputs?
 #
-# - **Dynamic and Flexible**: The keys and values in the namespace output are
-# not fixed and can change based on the task's execution.
-# - **Querying**: The data in the namespace output is stored as an AiiDA data
-# node, allowing for easy querying and retrieval.
-# - **Data Provenance**: When the data is used as input for subsequent tasks,
-# the origin of data is tracked.
+# - **Dynamic and Flexible**: The keys and values in the namespace output are not fixed and can change based on the task's execution. # noqa
+# - **Querying**: The data in the namespace output is stored as an AiiDA data node, allowing for easy querying and retrieval. # noqa
+# - **Data Provenance**: When the data is used as input for subsequent tasks, the origin of data is tracked.
 #
 # For example: Consider a molecule adsorption calculation where the namespace
 # output stores the surface slabs of the molecule adsorbed on different surface
@@ -332,7 +330,7 @@ for key, value in result["scaled_structures"].items():
 
 def add(x, y):
     sum = x + y
-    if (sum < 0).any():
+    if sum < 0:
         exit_code = {"status": 410, "message": "Some elements are negative"}
         return {"sum": sum, "exit_code": exit_code}
     return {"sum": sum}
@@ -347,6 +345,33 @@ result, node = run_get_node(PythonJob, inputs=inputs)
 print("exit_status:", node.exit_status)
 print("exit_message:", node.exit_message)
 
+######################################################################
+# Using `register_pickle_by_value`
+# --------------------------------
+#
+# If the function is defined inside an external module that is **not installed** on
+# the remote computer, this can cause import errors during execution.
+#
+# **Solution:**
+# By enabling `register_pickle_by_value=True`, the function is serialized **by value**
+# instead of being referenced by its module path. This embeds the function unpickled
+# even if the original module is unavailable on the remote computer.
+#
+# **Example:**
+#
+# .. code-block:: python
+#
+#     inputs = prepare_pythonjob_inputs(
+#         my_function,
+#         function_inputs={"x": 1, "y": 2},
+#         computer="localhost",
+#         register_pickle_by_value=True,  # Ensures function is embedded
+#     )
+#
+# **Important Considerations:**: If the function **contains import statements**,
+# the imported modules **must still be installed** on the remote computer.
+#
+
 
 ######################################################################
 # Define your data serializer and deserializer

aiida_pythonjob-0.2.0/docs/source/index.rst

@@ -0,0 +1,52 @@
+AiiDA PythonJob & PyFunction
+============================
+
+`PythonJob` and `pyfunction` enable users to run Python functions—either locally or remotely—with automatic serialization, provenance tracking, and workflow integration.
+
+These tools are designed to simplify the experience for users not familiar with AiiDA's internal types, allowing them to write pure Python functions while still benefiting from AiiDA's powerful infrastructure.
+
+**Key Features**
+
+1. **Remote Execution with PythonJob**  
+   Seamlessly run Python functions on a remote computer via `PythonJob`. A working directory is automatically created for the job, allowing full support for:
+   
+   - File upload and retrieval
+   - Parent/remote folders
+   - Integration with external codes (e.g. ASE + DFT engines)
+
+2. **Local Execution with PyFunction**  
+   Use `@pyfunction` to run pure Python functions locally. All inputs and outputs are automatically serialized/deserialized, enabling users to work with native Python types.  
+   This decorator is ideal for functions that are:
+   
+   .. note::
+      `pyfunction` does **not** create a dedicated working directory. It executes in the current local Python environment.  
+      File I/O or relative path access should be avoided unless explicitly handled.
+
+3. **User-Friendly Interface**  
+   Designed for users unfamiliar with AiiDA’s internal `Data` classes. The decorators handle all conversion and provenance tracking behind the scenes.
+
+4. **Workflow Management with Checkpoints**  
+   Combine `pyfunction` and `pythonjob` in `WorkGraph` workflows to build robust, restartable workflows with full checkpoint support.
+
+5. **Full Data Provenance**  
+   All inputs, outputs, and intermediate results are stored in the AiiDA provenance graph, ensuring reproducibility and traceability.
+
+**When to Use What**
+
++----------------+--------------------+---------------------+------------------+---------------------------------------------+
+| Decorator      | Execution          | Input/Output Types  | AiiDA Provenance | Recommended Use Case                        |
++================+====================+=====================+==================+=============================================+
+| ``@pyfunction``| Local              | Python native       | ✅ Yes           | Pure functions                              |
++----------------+--------------------+---------------------+------------------+---------------------------------------------+
+| ``@pythonjob`` | Remote             | Python native       | ✅ Yes           | Remote jobs with file handling              |
++----------------+--------------------+---------------------+------------------+---------------------------------------------+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+   :hidden:
+
+   installation
+   autogen/pythonjob
+   autogen/pyfunction
+   tutorial/index