mukip 0.4.0__py3-none-any.whl

mukip/__init__.py

@@ -0,0 +1,6 @@
+from .microkinetic_model import MicrokineticModel
+from .jvm_manager import initialize
+from .plot_2d import plot_2d
+
+__version__ = "0.4.0"
+__all__ = ['initialize', 'MicrokineticModel', 'plot_2d']

mukip/jvm_manager.py

@@ -0,0 +1,241 @@
+"""
+JVM management module with automatic JRE download and initialization.
+"""
+import os
+import sys
+import platform
+import urllib.request
+import ssl
+import zipfile
+import tarfile
+import shutil
+from pathlib import Path
+from typing import Optional, Tuple
+import jpype
+from jpype import JClass
+
+# Package root directory
+PACKAGE_DIR = Path(__file__).parent
+JRE_DIR = PACKAGE_DIR / "jre24"
+JAR_FILE = PACKAGE_DIR / "resources" / "mukip-0.4.0-beta-all.jar"
+
+MUKIP_INITIALIZED = False
+
+# JRE download configuration
+JRE_VERSION = "24.0.2_12"
+JRE_BASE_URL = "https://github.com/WestlakeUniversity-WangLab/jre8-mirror/releases/download"
+
+jvm_paths = {
+    'windows': JRE_DIR / 'bin' / 'server' / 'jvm.dll',
+    'linux': JRE_DIR / 'lib' / 'server' / 'libjvm.so',
+    'darwin': JRE_DIR / 'Contents' / 'Home' / 'lib' / 'server' / 'libjvm.dylib'
+}
+
+def detect_system_arch() -> Tuple[str, str]:
+    """
+    Detect system OS and architecture.
+
+    :return: Tuple of (system, arch) compatible with JRE downloads
+    """
+    raw_system = platform.system().lower()
+    raw_machine = platform.machine().lower()
+
+    if raw_system == "darwin":
+        system = "mac"
+    elif raw_system == "windows":
+        system = "windows"
+    elif raw_system == "linux":
+        system = "linux"
+    elif raw_system == "aix":
+        system = "aix"
+    else:
+        system = raw_system
+
+    if raw_machine in ["x86_64", "amd64"]:
+        arch = "x64"
+    elif raw_machine in ["arm64", "aarch64"]:
+        arch = "aarch64"
+    elif raw_machine in ["ppc64le", "powerpc64le"]:
+        arch = "ppc64le"
+    elif raw_machine == "s390x":
+        arch = "s390x"
+    elif raw_machine == "riscv64":
+        arch = "riscv64"
+    elif raw_machine.startswith("arm"):
+        arch = "arm"
+    else:
+        arch = raw_machine
+
+    if system == "linux":
+        if os.path.exists("/etc/alpine-release"):
+            system = "alpine-linux"
+
+    if not arch:
+        arch = raw_machine
+
+    return system, arch
+
+
+def get_jvm_library_path() -> Optional[str]:
+    """
+    Get the JVM library path for the downloaded JRE.
+
+    :return: Path to JVM library or None if not found
+    """
+    if not JRE_DIR.exists():
+        return None
+
+    system = platform.system().lower()
+    jvm_path = jvm_paths.get(system)
+    if jvm_path and jvm_path.exists():
+        return str(jvm_path)
+
+    return None
+
+
+def download_jre(progress_callback=None) -> bool:
+    """
+    Download and extract JRE from GitHub releases.
+
+    :param progress_callback: Optional callback function(step, percent)
+                          step: 'download' or 'extract'
+                          percent: 0-100
+    :return: True if successful, False otherwise
+    """
+    system, arch = detect_system_arch()
+    extension = "zip" if system == "windows" else "tar.gz"
+    filename = f"OpenJDK24U-jre_{arch}_{system}_hotspot_{JRE_VERSION}.{extension}"
+    download_url = f"{JRE_BASE_URL}/{JRE_VERSION}/{filename}"
+
+    temp_dir = PACKAGE_DIR / "temp_jre"
+    temp_dir.mkdir(exist_ok=True)
+    local_file = temp_dir / filename
+    try:
+
+        # Download with progress
+        def download_hook(block_num, block_size, total_size):
+            if progress_callback and total_size > 0:
+                downloaded = block_num * block_size
+                percent = int((downloaded * 100) / total_size)
+                progress_callback('download', min(percent, 100))
+
+        # Disable SSL verification for simplicity
+        ssl_context = ssl.create_default_context()
+        ssl_context.check_hostname = False
+        ssl_context.verify_mode = ssl.CERT_NONE
+
+        urllib.request.urlretrieve(download_url, str(local_file), reporthook=download_hook)
+
+        # Extract
+        extract_dir = temp_dir / "extracted"
+        extract_dir.mkdir(exist_ok=True)
+
+        if local_file.suffix == '.zip':
+            with zipfile.ZipFile(local_file, 'r') as zf:
+                members = zf.namelist()
+                total = len(members)
+                for i, member in enumerate(members):
+                    zf.extract(member, extract_dir)
+                    if progress_callback:
+                        progress_callback('extract', int((i + 1) * 100 / total))
+        else:
+            with tarfile.open(local_file, 'r:gz') as tf:
+                members = tf.getmembers()
+                total = len(members)
+                for i, member in enumerate(members):
+                    tf.extract(member, extract_dir)
+                    if progress_callback:
+                        progress_callback('extract', int((i + 1) * 100 / total))
+
+        # Move extracted JRE to target directory
+        if JRE_DIR.exists():
+            shutil.rmtree(JRE_DIR)
+
+        # Find the actual JRE directory
+        extracted_items = list(extract_dir.iterdir())
+        if len(extracted_items) == 1 and extracted_items[0].is_dir():
+            # Single directory containing JRE
+            shutil.move(str(extracted_items[0]), str(JRE_DIR))
+        else:
+            # Multiple items, move them all
+            JRE_DIR.mkdir(exist_ok=True)
+            for item in extracted_items:
+                shutil.move(str(item), str(JRE_DIR / item.name))
+
+        # Cleanup
+        shutil.rmtree(temp_dir)
+
+        return get_jvm_library_path() is not None
+
+    except Exception as e:
+        print(f"Failed to download/extract JRE: {e}", file=sys.stderr)
+        print("Please check your network connection and retry.", file=sys.stderr)
+        print("If the problem persists, please download it manually:", file=sys.stderr)
+        print(f"1. Download: {download_url}", file=sys.stderr)
+        print(f"2. Extract the contents to: {JRE_DIR}", file=sys.stderr)
+        print(f"3. Ensure the file exists: {jvm_paths.get(platform.system().lower())}.", file=sys.stderr)
+        return False
+
+
+def ensure_jre() -> bool:
+    """
+    Ensure JRE is available, download if not present.
+
+    :return: True if JRE is ready, False otherwise
+    """
+    if get_jvm_library_path():
+        return True
+
+    print("JRE not found. Downloading... (first-time setup only)")
+
+    def progress_callback(step, percent):
+        if step == 'download':
+            print(f"\rDownloading: {percent}%", end='', flush=True)
+        elif step == 'extract':
+            print(f"\rExtracting: {percent}%", end='', flush=True)
+
+    success = download_jre(progress_callback)
+    if success:
+        print("\nJRE installation complete!")
+    else:
+        print("\nJRE installation failed!")
+
+    return success
+
+
+def start_jvm():
+    jvm_path = get_jvm_library_path()
+    if not jvm_path:
+        if not ensure_jre():
+            return False
+        jvm_path = get_jvm_library_path()
+        if not jvm_path:
+            return False
+
+    try:
+        jpype.startJVM(jvm_path, classpath=[JAR_FILE], convertStrings=False)
+        return jpype.isJVMStarted()
+    except Exception as e:
+        print(f"Failed to start JVM: {e}", file=sys.stderr)
+        return False
+
+
+def initialize():
+    """
+    Initialize JVM and run MuKiP initialization.
+    This should be called before any MuKiP functions.
+    """
+    global MUKIP_INITIALIZED
+    if MUKIP_INITIALIZED:
+        return
+    try:
+        if not jpype.isJVMStarted():
+            start_jvm()
+        JClass("com.wang_lab.mukip.components.ComponentsLoader").initializeComponents("")
+        MUKIP_INITIALIZED = True
+    except Exception as e:
+        print(f"MuKiP initialization failed: {e}", file=sys.stderr)
+
+def get_class(classpath: str):
+    initialize()
+    return JClass(classpath)

mukip/microkinetic_model.py

@@ -0,0 +1,154 @@
+import multiprocessing
+from typing import Literal
+import jpype
+
+from mukip.plot_2d import plot_2d
+from mukip.jvm_manager import get_class
+
+
+def _wrap_thermo(thermo):
+    return {str(k): float(v) for k, v in thermo.getValues().items()}
+
+def _wrap_vector(vector):
+    return [float(b.doubleValue()) for b in vector]
+
+def _wrap_double_array(array):
+    return [float(d) for d in array]
+
+class MicrokineticModel:
+    """
+    A wrapped class for microkinetic modeling.
+    """
+    MKM = get_class("com.wang_lab.mukip.components.model.MicrokineticModel").class_.getField("Companion").get(None)
+    ArrayList = get_class('java.util.ArrayList')
+    LinkedHashMap = get_class("java.util.LinkedHashMap")
+    GridPoint = get_class("com.wang_lab.mukip.point.GridPoint")
+    MapPoint = get_class("com.wang_lab.mukip.point.MapPoint")
+    JUtils = get_class("com.wang_lab.mukip.MuKiPUtils")
+    Adsorbate = get_class("com.wang_lab.mukip.species.Adsorbate")
+    Gas = get_class("com.wang_lab.mukip.species.Gas")
+    Fluid = get_class("com.wang_lab.mukip.species.Fluid")
+    Aqua = get_class("com.wang_lab.mukip.species.Aqua")
+    n_cpu = multiprocessing.cpu_count()
+    def __init__(self, setup_file: str):
+        """
+        Create a new MicrokineticModel object.
+
+        :param setup_file: The path of the setup file for microkinetic model
+        """
+        self.setup_file = setup_file
+        self.model = self.MKM.reactionModel(jpype.JString(self.setup_file))
+
+    def load_data(self):
+        """
+        Load solutions for each point from the data file.
+        """
+        self.model.loadData()
+
+    def save_data(self):
+        """
+        Save solutions on each point to the data file.
+        """
+        self.model.saveData()
+
+    def _get_grid_point(self, *index: int):
+        return self.model.getPoint(self.GridPoint(*index))
+
+    def get_global_thermo(self):
+        """
+        Get global thermodynamic data.
+        :return: A dictionary of all global thermodynamic variables.
+        """
+        return _wrap_thermo(self.model.getThermo())
+
+    def get_grid_thermo(self, *index: int):
+        """
+        Get the thermodynamic data of a grid point.
+        :param index: The index of the grid point.
+        :return: A dictionary of all thermodynamic variables on this point.
+        """
+        return _wrap_thermo(self._get_grid_point(*index).getThermo())
+
+    def run(self, method: Literal['map_sample', 'map_in_turn', 'map_expand', 'map_check']='map_sample', n_thread: int = n_cpu):
+        """
+        Run the microkinetic model with given method.
+        :param method: The method to use to run the microkinetic model.
+            - 'map_sample': Use sampling-expansion method (SEM), which boasts high solving efficiency and stability
+            , and is highly recommended.
+            - 'map_in_turn': Solve all points in turn.
+            - 'map_expand': Solve all unsolved points from points with solution. It should be used when a partial set
+            of points are successfully solved.
+            - 'map_check': Check existing solutions on all points in turn. If the solution on a point is incorrect,
+            it will attempt to solve it. If the solution fails, the data will be deleted to ensure that
+            all solutions are correct after the method is completed.
+        :param n_thread: Number of threads to use.
+        """
+        self.model.getMapper().map(method, n_thread, self.ArrayList(), None)
+
+    def get_result(self, *index: int):
+        """
+        Get results on a point.
+        :param index: The index of the grid point.
+        :return: Results as a dictionary.
+        """
+        pt = self._get_grid_point(*index)
+        results = {}
+        if r := pt.getCoverage():
+            adsorbates = self.model.get(self.Adsorbate)
+            coverage = _wrap_vector(r)
+            results["coverage"] = {str(ads.getName()): c for ads, c in zip(adsorbates, coverage)}
+        if r := pt.getTof():
+            fluids = self.model.get(self.Fluid)
+            tof = _wrap_double_array(r)
+            results["TOF"] = {str(gas.getName()): p for gas, p in zip(fluids, tof)}
+        if r := pt.getCurrent():
+            results["current"] = float(r)
+        if r := pt.getPressure():
+            gases = self.model.get(self.Gas)
+            pressure = _wrap_vector(r)
+            results["pressure"] = {str(gas.getName()): p for gas, p in zip(gases, pressure)}
+        if r := pt.getConcentration():
+            aquas = self.model.get(self.Aqua)
+            concentration = _wrap_vector(r)
+            results["concentration"] = {str(aq.getName()): c for aq, c in zip(aquas, concentration)}
+        return results
+
+    def get_variables(self, *index: int):
+        """
+        Get all fined variables on a point.
+        :param index: The index of the grid point.
+        :return: Fined variables as a dictionary.
+        """
+        pt = self._get_grid_point(*index)
+        variables = self.model.getSolver().getFinePointValues(pt)
+        results = {str(k): float(v.doubleValue()) for k, v in variables.items()}
+        expressions = self.model.getSolver().getExpressionDictionary()
+        buffer = self.LinkedHashMap()
+        for k, v in expressions.items():
+            results[k] = float(self.JUtils.toDouble(v.arithmetic(variables, expressions, buffer)))
+        return results
+
+    def write(self, plot: bool = False, fig_size=None, contour_kw=None, clabel_kw=None, contourf_kw=None):
+        """
+        Write data with writers defined in the setup file.
+            :param plot: Whether to generate and save plots along with data.
+            Default: False
+        :param fig_size: Figure size in inches as a tuple (width, height).
+            Default: (9, 6)
+        :param contour_kw: Keyword arguments passed to matplotlib's contour() for contour lines.
+            Default: {'levels': 31, 'colors': 'black', 'linewidths': 0.5}
+        :param clabel_kw: Keyword arguments passed to matplotlib's clabel() for contour labels.
+            Default: {'inline': True, 'fontsize': 8}
+        :param contourf_kw: Keyword arguments passed to matplotlib's contourf() for filled contours.
+            Default: {'levels': 31, 'cmap': 'jet'}
+        """
+        for writer in self.model.getWriters():
+            writer.output()
+            if plot:
+                class_name = writer.__class__.__name__
+                csv_path = str(writer.getOutputFile().getAbsolutePath())
+                if class_name == "com.wang_lab.mukip.components.writer.CSV2DCustomWriter":
+                    plot_2d(csv_path, fig_size, contour_kw, clabel_kw, contourf_kw)
+                else:
+                    print(f"Plot method for {class_name} not implemented")
+

mukip/plot_2d.py

@@ -0,0 +1,101 @@
+import os
+import csv
+import numpy as np
+
+import matplotlib
+matplotlib.use('Agg')
+
+import matplotlib.pyplot as plt
+
+def parse_axis_labels(label_str):
+    """Extract A (Y-axis label) and B (X-axis label) from a string like 'A\\B'"""
+    label_str = label_str.strip()
+    if '\\' in label_str:
+        a, b = label_str.split('\\', 1)
+        return a.strip(), b.strip()
+    else:
+        return "Y", "X"
+
+def read_csv_matrix(file_path):
+    """Read CSV file into a 2D list of strings"""
+    with open(file_path, newline='', encoding='utf-8') as f:
+        reader = csv.reader(f)
+        matrix = [row for row in reader]
+    return matrix
+
+def to_float_or_nan(s):
+    """Convert string to float; return np.nan if conversion fails"""
+    try:
+        return float(s)
+    except ValueError:
+        return np.nan
+
+def plot_2d(csv_path, fig_size=None, contour_kw=None, clabel_kw=None, contourf_kw=None):
+    # Read raw data
+    data = read_csv_matrix(csv_path)
+    title = os.path.splitext(os.path.basename(csv_path))[0]
+
+    if not data or len(data) < 2 or len(data[0]) < 2:
+        raise ValueError("Invalid CSV format: at least a 2x2 grid (including header) is required.")
+
+    # Parse top-left cell (e.g., "A\\B")
+    top_left = data[0][0]
+    ylabel, xlabel = parse_axis_labels(top_left)
+
+    # Extract X values (first row, skip first element)
+    x_vals_str = data[0][1:]
+    x_vals = np.array([to_float_or_nan(x) for x in x_vals_str])
+    x_vals = x_vals[~np.isnan(x_vals)]
+
+    # Extract Y values (first column, skip first element)
+    y_vals_str = [row[0] for row in data[1:]]
+    y_vals = np.array([to_float_or_nan(y) for y in y_vals_str])
+    y_vals = y_vals[~np.isnan(y_vals)]
+
+    # Extract Z data
+    z_rows = []
+    for i in range(1, len(data)):
+        row = data[i]
+        z_row = []
+        for j in range(1, min(len(row), len(x_vals_str) + 1)):
+            z_row.append(to_float_or_nan(row[j]))
+        while len(z_row) < len(x_vals):
+            z_row.append(np.nan)
+        z_rows.append(z_row[:len(x_vals)])
+    
+    Z = np.array(z_rows, dtype=float)
+
+    # Validate dimensions
+    if Z.shape[0] != len(y_vals) or Z.shape[1] != len(x_vals):
+        print(f"Warning: Data shape {Z.shape} doesn't match Y({len(y_vals)}) × X({len(x_vals)}).")
+
+    # Create meshgrid
+    X, Y = np.meshgrid(x_vals, y_vals)
+
+    # Check for non-positive values (log undefined for <= 0)
+    Z = np.log10(Z)
+
+    # Plot
+    if not fig_size:
+        fig_size = (9, 6)
+    plt.figure(figsize=fig_size)
+
+    # Use LogNorm for logarithmic color scale
+    if not contour_kw:
+        contour_kw = {'levels': 31, 'colors': 'black', 'linewidths': 0.5}
+    contour = plt.contour(X, Y, Z, **contour_kw)
+
+    if not clabel_kw:
+        clabel_kw = {'inline': True, 'fontsize': 8}
+    plt.clabel(contour, **clabel_kw)
+
+    if not contourf_kw:
+        contourf_kw = {'levels': 31, 'cmap': 'jet'}
+    filled = plt.contourf(X, Y, Z, **contourf_kw)
+    plt.colorbar(filled)
+
+    plt.xlabel(xlabel)
+    plt.ylabel(ylabel)
+    plt.title(f'log({title})')
+    plt.tight_layout()
+    plt.savefig(csv_path.replace('.csv', '.png'))