permeability 0.1.0__py3-none-any.whl

permeability/__init__.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from permeability!")
+
+
+if __name__ == "__main__":
+    main()

permeability/mcp/ProcessResult.py

@@ -0,0 +1,14 @@
+from typing import Any
+
+
+# Process result for calculation
+def process_mcp_calculation_result(
+        value: Any,
+        unit: str,
+        meaning: str,
+) -> dict:
+    return {
+        "val": value,
+        "unit": unit,
+        "meaning": meaning,
+    }

permeability/mcp/Prompts.py

@@ -0,0 +1,59 @@
+# Instructions
+mcp_instruction = """
+Provide tools for scientific calculations related to Material Science.
+"""
+permeability_calculation_instruction = """
+Calculate permeability using the seepage distance method.
+K = L² · μ · φ / (2 · t · ΔP)
+If you fill the p_c field that is optional to fill, you will get the result corrected by the capillary pressure:
+K = μ · φ · L² / (2 · t · (ΔP + p_c))
+"""
+infiltration_time_calculation_instruction = """
+Calculate total time for fluid to fully penetrate the sample.
+t = μ · φ · L² / (2 · K · ΔP)
+If you fill the p_c field that is optional to fill, you will get the result corrected by the capillary pressure:
+t = μ · φ · L² / (2 · K · (ΔP + p_c))
+"""
+m22darcy_instruction = """
+Convert m^2 to Darcy
+"""
+darcy2m2_instruction = """
+Convert Darcy to m^2
+"""
+infiltration_front_position_instruction = """
+Calculate infiltration front position at given time(s).
+z(t) = sqrt(2 · K · ΔP · t / (μ · φ))
+If you fill the p_c field that is optional to fill, you will get the result corrected by the capillary pressure:
+z(t) = sqrt(2 · K · (ΔP + p_c) · t / (μ · φ))
+"""
+infiltration_front_position_multiple_time_instruction = """
+Calculate infiltration front position at multiple times (for graph making).
+z(t) = sqrt(2 · K · ΔP · t / (μ · φ))
+If you fill the p_c field that is optional to fill, you will get the result corrected by the capillary pressure:
+z(t) = sqrt(2 · K · (ΔP + p_c) · t / (μ · φ))
+"""
+capillary_pressure_calculation_instruction = """
+Calculate capillary pressure using the Young-Laplace equation.
+pc = 2 · γ · cos(θ) / r
+"""
+pressure_difference_calculation_instruction = """
+Calculate pressure difference using the seepage distance method.
+ΔP = μ · φ · L² / (2 · K · t)
+If you fill the p_c field that is optional to fill, you will get the result corrected by the capillary pressure:
+ΔP = μ · φ · L² / (2 · K · t) - p_c
+"""
+# Seepage Distance Calculation
+L_meaning = "Sample length/thickness along flow direction (m)"
+mu_meaning = "Dynamic viscosity of the fluid (Pa·s)"
+phi_meaning = "Porosity of the porous medium (dimensionless, 0 < phi <= 1)"
+t_meaning = "Total time for fluid to fully penetrate the sample (s)"
+multi_t_meaning = "Total time recorded for multiple rounds for fluid to fully penetrate the sample (s)"
+dP_meaning = "Constant pressure difference across the sample (Pa)"
+K_meaning = "Permeability (m²)"
+m2K_meaning = "Permeability in m^2"
+darcyK_meaning = "Permeability in Darcy"
+z_meaning = "Infiltration front position at given time(s)"
+p_c_meaning = "Capillary pressure (Pa)"
+theta_meaning = "Contact angle (wetting angle) (Degrees)"
+gamma_meaning = "Surface tension of the liquid (N/m)"
+r_meaning = "Equivalent pore radius (m)"

permeability/mcp/Server.py

@@ -0,0 +1,343 @@
+from typing import (
+    Annotated,
+    List,
+    Optional
+)
+import argparse
+import numpy as np
+# Fastmcp dependencies
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+# Project dependencies
+from permeability.mcp.ProcessResult import (
+    process_mcp_calculation_result
+)
+from permeability.mcp.Prompts import (
+    mcp_instruction,
+    permeability_calculation_instruction,
+    infiltration_time_calculation_instruction,
+    darcy2m2_instruction,
+    m22darcy_instruction,
+    infiltration_front_position_instruction,
+    infiltration_front_position_multiple_time_instruction,
+    capillary_pressure_calculation_instruction,
+    pressure_difference_calculation_instruction,
+    L_meaning,
+    mu_meaning,
+    phi_meaning,
+    t_meaning,
+    dP_meaning,
+    K_meaning,
+    multi_t_meaning,
+    darcyK_meaning,
+    m2K_meaning,
+    z_meaning,
+    p_c_meaning,
+    gamma_meaning,
+    theta_meaning,
+    r_meaning
+)
+from permeability.permeability.Seepage import (
+    calculate_permeability,
+    calculate_infiltration_time,
+    calculate_infiltration_front_position,
+    calculate_infiltration_front_position_with_multiple_time,
+    calculate_pressure_difference
+)
+from permeability.permeability.Capillary import (
+    calculate_permeability_with_capillary_correction,
+    calculate_infiltration_time_with_capillary_correction,
+    calculate_infiltration_front_position_with_capillary_correction,
+    calculate_infiltration_front_position_with_multiple_time_with_capillary_correction,
+    calculate_capillary_pressure,
+    calculate_pressure_difference_with_capillary_correction
+)
+from permeability.utils.UnitConverter import (
+    darcy2m2,
+    m22darcy
+)
+
+
+# mcp
+mcp = FastMCP(
+    "Permeability MCP",
+    strict_input_validation=True,
+    mask_error_details=True,
+    instructions=mcp_instruction
+)
+
+
+# Calculate permeability
+@mcp.tool(
+    name="calculate_permeability_by_seepage_distance",
+    description=permeability_calculation_instruction,
+    tags={"permeability", "scalar_calculation"}
+)
+async def calculate_permeability_by_seepage_distance(
+        L: Annotated[float, L_meaning],
+        mu: Annotated[float, mu_meaning],
+        phi: Annotated[float, phi_meaning],
+        t: Annotated[float, t_meaning],
+        dP: Annotated[float, dP_meaning],
+        p_c: Optional[Annotated[float, p_c_meaning]] = None
+) -> dict:
+    try:
+        if p_c is None:
+            calculation_result = calculate_permeability(
+                L=L,
+                mu=mu,
+                phi=phi,
+                t=t,
+                dP=dP
+            )
+        else:
+            calculation_result = calculate_permeability_with_capillary_correction(
+                L=L,
+                mu=mu,
+                phi=phi,
+                t=t,
+                dP=dP,
+                p_c=p_c
+            )
+        return process_mcp_calculation_result(
+            value=calculation_result,
+            unit="m^2",
+            meaning=K_meaning
+        )
+    except Exception as e:
+        raise ToolError(e)
+
+
+# Infiltration time calculation
+@mcp.tool(
+    name="calculate_infiltration_time",
+    description=infiltration_time_calculation_instruction,
+    tags={"permeability", "scalar_calculation"}
+)
+async def calculate_infiltration_time_tool(
+        L: Annotated[float, L_meaning],
+        mu: Annotated[float, mu_meaning],
+        phi: Annotated[float, phi_meaning],
+        K: Annotated[float, K_meaning],
+        dP: Annotated[float, dP_meaning],
+        p_c: Optional[Annotated[float, p_c_meaning]] = None
+) -> dict:
+    try:
+        if p_c is None:
+            calculation_result = calculate_infiltration_time(
+                L=L,
+                mu=mu,
+                phi=phi,
+                K=K,
+                dP=dP
+            )
+        else:
+            calculation_result = calculate_infiltration_time_with_capillary_correction(
+                L=L,
+                mu=mu,
+                phi=phi,
+                K=K,
+                dP=dP,
+                p_c=p_c
+            )
+        return process_mcp_calculation_result(
+            value=calculation_result,
+            unit="s",
+            meaning=t_meaning
+        )
+    except Exception as e:
+        raise ToolError(e)
+
+
+# Tool for converting darcy to m2
+@mcp.tool(
+    name="darcy_to_m2_converter",
+    description=darcy2m2_instruction,
+    tags={"permeability", "unit_converter"}
+)
+async def darcy_to_m2_converter(
+        darcyK: Annotated[float, darcyK_meaning],
+) -> dict:
+    calculation_result = darcy2m2(darcyK=darcyK)
+    return process_mcp_calculation_result(
+        value=calculation_result,
+        unit="m^2",
+        meaning=m2K_meaning
+    )
+
+
+# Tool for converting m2 to darcy
+@mcp.tool(
+    name="m2_to_darcy_converter",
+    description=m22darcy_instruction,
+    tags={"permeability", "unit_converter"}
+)
+async def m2_to_darcy_converter(
+        m2K: Annotated[float, m2K_meaning],
+) -> dict:
+    calculation_result = m22darcy(m2K=m2K)
+    return process_mcp_calculation_result(
+        value=calculation_result,
+        unit="Darcy",
+        meaning=darcyK_meaning
+    )
+
+
+# Tool for calculating infiltration front position
+@mcp.tool(
+    name="calculate_infiltration_front_position",
+    description=infiltration_front_position_instruction,
+    tags={"permeability", "scalar_calculation"}
+)
+async def calculate_infiltration_front_position_tool(
+        K: Annotated[float, K_meaning],
+        mu: Annotated[float, mu_meaning],
+        phi: Annotated[float, phi_meaning],
+        dP: Annotated[float, dP_meaning],
+        t: Annotated[float, t_meaning],
+        p_c: Optional[Annotated[float, p_c_meaning]] = None
+) -> dict:
+    try:
+        if p_c is None:
+            calculation_result = calculate_infiltration_front_position(
+                K=K,
+                mu=mu,
+                phi=phi,
+                t=t,
+                dP=dP
+            )
+        else:
+            calculation_result = calculate_infiltration_front_position_with_capillary_correction(
+                K=K,
+                mu=mu,
+                phi=phi,
+                t=t,
+                dP=dP,
+                p_c=p_c
+            )
+        return process_mcp_calculation_result(
+            value=calculation_result,
+            unit="m",
+            meaning=z_meaning
+        )
+    except Exception as e:
+        raise ToolError(e)
+
+
+# Tool for calculating infiltration front position for multiple time points
+@mcp.tool(
+    name="calculate_infiltration_front_position4multiple_times",
+    description=infiltration_front_position_multiple_time_instruction,
+    tags={"permeability", "graph_related", "vector_calculation"}
+)
+async def calculate_infiltration_front_position4multiple_times_tool(
+    K: Annotated[float, K_meaning],
+        mu: Annotated[float, mu_meaning],
+        phi: Annotated[float, phi_meaning],
+        dP: Annotated[float, dP_meaning],
+        t: Annotated[List[float], multi_t_meaning],
+        p_c: Optional[Annotated[float, p_c_meaning]] = None
+) -> dict:
+    try:
+        processed_t = np.array(t)
+        if p_c is None:
+            calculation_result = calculate_infiltration_front_position_with_multiple_time(
+                K=K,
+                mu=mu,
+                phi=phi,
+                t=processed_t,
+                dP=dP
+            )
+        else:
+            calculation_result = (
+                calculate_infiltration_front_position_with_multiple_time_with_capillary_correction(
+                    K=K,
+                    mu=mu,
+                    phi=phi,
+                    t=processed_t,
+                    dP=dP,
+                    p_c=p_c
+                )
+            )
+        return process_mcp_calculation_result(
+            value=calculation_result.tolist(),
+            unit="m",
+            meaning=z_meaning
+        )
+    except Exception as e:
+        raise ToolError(e)
+
+
+# Calculate capillary pressure
+@mcp.tool(
+    name="calculate_capillary_pressure",
+    description=capillary_pressure_calculation_instruction,
+    tags={"permeability", "scalar_calculation"}
+)
+async def calculate_capillary_pressure_tool(
+        theta: Annotated[float, theta_meaning],
+        r: Annotated[float, r_meaning],
+        gamma: Annotated[float, gamma_meaning],
+):
+    try:
+        calculation_result = calculate_capillary_pressure(
+            theta=theta,
+            r=r,
+            gamma=gamma
+        )
+        return process_mcp_calculation_result(
+            value=calculation_result,
+            unit="Pa",
+            meaning=p_c_meaning
+        )
+    except Exception as e:
+        raise ToolError(e)
+
+
+# Calculate pressure difference
+@mcp.tool(
+    name="calculate_pressure_difference",
+    description=pressure_difference_calculation_instruction,
+    tags={"permeability", "scalar_calculation"}
+)
+async def calculate_pressure_difference_tool(
+        L: Annotated[float, L_meaning],
+        mu: Annotated[float, mu_meaning],
+        phi: Annotated[float, phi_meaning],
+        K: Annotated[float, K_meaning],
+        t: Annotated[float, t_meaning],
+        p_c: Optional[Annotated[float, p_c_meaning]] = None,
+):
+    try:
+        if p_c is None:
+            calculation_result = calculate_pressure_difference(
+                L=L,
+                mu=mu,
+                phi=phi,
+                K=K,
+                t=t
+            )
+        else:
+            calculation_result = calculate_pressure_difference_with_capillary_correction(
+                L=L,
+                mu=mu,
+                phi=phi,
+                K=K,
+                t=t,
+                p_c=p_c
+            )
+        return process_mcp_calculation_result(
+            value=calculation_result,
+            unit="Pa",
+            meaning=dP_meaning
+        )
+    except Exception as e:
+        raise ToolError(e)
+
+
+# Run
+def run():
+    parser = argparse.ArgumentParser(description="My MCP Server")
+    parser.add_argument("--port", type=int, default=8000, help="Port for SSE transport")
+    args = parser.parse_args()
+    mcp.run(transport="http", host="localhost", port=args.port)

permeability/permeability/Capillary.py

@@ -0,0 +1,179 @@
+import numpy as np
+
+
+def calculate_capillary_pressure(
+        gamma: float,
+        theta: float,
+        r: float
+) -> float:
+    '''
+    Calculate capillary pressure using the Young-Laplace equation.
+    p_c = 2 · γ · cos(θ) / r
+    :param gamma: Surface tension of the liquid (N/m)
+    :param theta: Contact angle (wetting angle) (Degrees)
+    :param r: Equivalent pore radius (m)
+    :return: p_c, capillary pressure (Pa)
+    '''
+    if gamma <= 0:
+        raise ValueError('gamma must be greater than 0')
+    if r <= 0:
+        raise ValueError('r must be greater than 0')
+    rad_theta = np.deg2rad(theta)
+    return (2*gamma*np.cos(rad_theta))/r
+
+
+def calculate_permeability_with_capillary_correction(
+        p_c: float,
+        L: float,
+        mu: float,
+        phi: float,
+        t: float,
+        dP: float,
+):
+    '''
+    Calculate permeability with capillary force correction.
+    K = μ · φ · L² / (2 · t · (ΔP + p_c))
+    :param p_c: capillary pressure (Pa)
+    :param L: Sample length/thickness along flow direction (m)
+    :param mu: Dynamic viscosity of the fluid (Pa·s)
+    :param phi: Porosity of the porous medium (dimensionless, 0 < phi <= 1)
+    :param t: Total time for fluid to fully penetrate the sample (s)
+    :param dP: Constant pressure difference across the sample (Pa)
+    :return: K, Permeability (m^2)
+    '''
+    if dP <= 0 or t <= 0:
+        raise ValueError("dP and t cannot be smaller than 0")
+    if mu <= 0:
+        raise ValueError("mu cannot be <= 0")
+    if phi > 1 or phi < 0:
+        raise ValueError("phi must be between 0 and 1")
+    if L <= 0:
+        raise ValueError("L must be greater than 0")
+    if p_c == -dP:
+        raise ValueError("p_c + dP cannot be equal to 0")
+    return (L * L * mu * phi) / (2 * t * (dP + p_c))
+
+
+def calculate_infiltration_time_with_capillary_correction(
+        p_c: float,
+        L: float,
+        mu: float,
+        phi: float,
+        K: float,
+        dP: float
+) -> float:
+    '''
+    Calculate permeability with capillary force correction.
+    t = μ · φ · L² / (2 · K · (ΔP + p_c))
+    :param p_c: capillary pressure (Pa)
+    :param L: Sample length/thickness along flow direction (m)
+    :param mu: Dynamic viscosity of the fluid (Pa·s)
+    :param phi: Porosity of the porous medium (dimensionless, 0 < phi <= 1)
+    :param K: Permeability (m^2)
+    :param dP: Constant pressure difference across the sample (Pa)
+    :return: t, Total time for fluid to fully penetrate the sample (s)
+    '''
+    if K <= 0 or dP <= 0:
+        raise ValueError("dP and K cannot be smaller than 0")
+    if mu <= 0:
+        raise ValueError("mu cannot be <= 0")
+    if phi > 1 or phi < 0:
+        raise ValueError("phi must be between 0 and 1")
+    if L <= 0:
+        raise ValueError("L must be greater than 0")
+    if p_c == -dP:
+        raise ValueError("p_c + dP != 0")
+    return (mu * phi * L * L) / (2 * K * (dP+p_c))
+
+
+def calculate_infiltration_front_position_with_capillary_correction(
+        K: float,
+        mu: float,
+        phi: float,
+        dP: float,
+        t: float,
+        p_c: float
+) -> float:
+    '''
+    Calculate infiltration front position with capillary force correction at given time(s).
+    z(t) = sqrt(2 · K · (ΔP + p_c) · t / (μ · φ))
+    :param K: Permeability (m^2)
+    :param p_c: capillary pressure (Pa)
+    :param mu: Dynamic viscosity of the fluid (Pa·s)
+    :param phi: Porosity of the porous medium (dimensionless, 0 < phi <= 1)
+    :param dP: Constant pressure difference across the sample (Pa)
+    :param t: Total time recorded for fluid to fully penetrate the sample (s)
+    :return: z, the infiltration front position at given time
+    '''
+    if mu <= 0 or phi <= 0:
+        raise ValueError("mu and phi cannot be smaller than 0")
+    if phi > 1 or phi < 0:
+        raise ValueError("phi must be between 0 and 1")
+    if K <= 0:
+        raise ValueError("K must be greater than 0")
+    if t < 0:
+        raise ValueError("t must be greater than 0")
+    if dP <= 0:
+        raise ValueError("dP must be greater than 0")
+    return np.sqrt((2 * K * (dP+p_c) * t) / (mu * phi))
+
+
+def calculate_infiltration_front_position_with_multiple_time_with_capillary_correction(
+        K: float,
+        mu: float,
+        phi: float,
+        dP: float,
+        t: np.ndarray,
+        p_c: float
+) -> np.ndarray:
+    '''
+    Calculate infiltration front position with capillary force correction at multiple times (for graph making).
+    z(t) = sqrt(2 · K · (ΔP + p_c) · t / (μ · φ))
+    :param p_c: capillary pressure (Pa)
+    :param K: Permeability (m^2)
+    :param mu: Dynamic viscosity of the fluid (Pa·s)
+    :param phi: Porosity of the porous medium (dimensionless, 0 < phi <= 1)
+    :param dP: Constant pressure difference across the sample (Pa)
+    :param t: Total time recorded for multiple rounds for fluid to fully penetrate the sample (s)
+    :return: z, the infiltration front position at given time
+    '''
+    if mu <= 0 or phi <= 0:
+        raise ValueError("mu and phi cannot be smaller than 0")
+    if phi > 1 or phi < 0:
+        raise ValueError("phi must be between 0 and 1")
+    if K <= 0:
+        raise ValueError("K must be greater than 0")
+    if not np.all(t >= 0):
+        raise ValueError("t must be greater than 0")
+    if dP <= 0:
+        raise ValueError("dP must be greater than 0")
+    return np.sqrt((2 * K * (dP+p_c) * t) / (mu * phi))
+
+
+def calculate_pressure_difference_with_capillary_correction(
+        L: float,
+        mu: float,
+        phi: float,
+        K: float,
+        t: float,
+        p_c: float
+) -> float:
+    '''
+    Calculate pressure difference using the seepage distance method with capillary correction.
+    ΔP = μ · φ · L² / (2 · K · t) - p_c
+    :param L: Sample length/thickness along flow direction (m)
+    :param mu: Dynamic viscosity of the fluid (Pa·s)
+    :param phi: Porosity of the porous medium (dimensionless, 0 < phi <= 1)
+    :param K: Permeability (m^2)
+    :param t, Total time for fluid to fully penetrate the sample (s)
+    :return: dP, Constant pressure difference across the sample (Pa)
+    '''
+    if K <= 0 or t <= 0:
+        raise ValueError("dP and K cannot be smaller than 0")
+    if mu <= 0:
+        raise ValueError("mu cannot be <= 0")
+    if phi > 1 or phi < 0:
+        raise ValueError("phi must be between 0 and 1")
+    if L <= 0:
+        raise ValueError("L must be greater than 0")
+    return (mu * phi * L * L) / (2 * K * t) - p_c