oil_api_from_sg
Convert oil specific gravity to API gravity using the standard industry formula. Essential for standardizing oil property reporting and classification in petroleum engineering.
Instructions
Convert oil specific gravity to API gravity.
UNIT CONVERSION TOOL - Converts oil specific gravity (dimensionless, water=1.0) to API gravity (degrees). API gravity is an inverse measure of density - higher API means lighter oil. Essential for standardizing oil property reporting.
Parameters:
sg (float or list, required): Oil specific gravity (water=1.0). Valid range: 0.1-1.5. Typical: 0.8-1.0. Example: 0.85 or [0.80, 0.85, 0.90]. Can be scalar or array.
Conversion Formula: API = (141.5 / SG) - 131.5
API Gravity Ranges:
Heavy oil: API < 22° (SG > 0.922)
Medium oil: API 22-35° (SG 0.922-0.850)
Light oil: API > 35° (SG < 0.850)
Water: API = 10° (SG = 1.0)
Returns: Dictionary with:
value (float or list): API gravity in degrees (matches input sg shape)
method (str): "Standard conversion"
units (str): "degrees API"
inputs (dict): Echo of input parameters
Common Mistakes:
Using gas specific gravity instead of oil specific gravity
Confusing API gravity with specific gravity (inverse relationship)
Using density (lb/cuft) instead of specific gravity
Not understanding that higher API = lighter oil
Example Usage:
Result: API = (141.5 / 0.85) - 131.5 ≈ 35.0° (medium gravity oil)
Note: API gravity is the industry standard for oil classification. Use this conversion when you have specific gravity but need API gravity for correlations or reporting.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Input Schema (JSON Schema)
Implementation Reference
- Handler function that implements the core logic of converting specific gravity (SG) to API gravity using pyrestoolbox.oil.oil_api, with input validation via Pydantic and JSON-compatible output formatting.@mcp.tool() def oil_api_from_sg(request: SGConversionRequest) -> dict: """Convert oil specific gravity to API gravity. **UNIT CONVERSION TOOL** - Converts oil specific gravity (dimensionless, water=1.0) to API gravity (degrees). API gravity is an inverse measure of density - higher API means lighter oil. Essential for standardizing oil property reporting. **Parameters:** - **sg** (float or list, required): Oil specific gravity (water=1.0). Valid range: 0.1-1.5. Typical: 0.8-1.0. Example: 0.85 or [0.80, 0.85, 0.90]. Can be scalar or array. **Conversion Formula:** API = (141.5 / SG) - 131.5 **API Gravity Ranges:** - Heavy oil: API < 22° (SG > 0.922) - Medium oil: API 22-35° (SG 0.922-0.850) - Light oil: API > 35° (SG < 0.850) - Water: API = 10° (SG = 1.0) **Returns:** Dictionary with: - **value** (float or list): API gravity in degrees (matches input sg shape) - **method** (str): "Standard conversion" - **units** (str): "degrees API" - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Using gas specific gravity instead of oil specific gravity - Confusing API gravity with specific gravity (inverse relationship) - Using density (lb/cuft) instead of specific gravity - Not understanding that higher API = lighter oil **Example Usage:** ```python { "sg": 0.85 } ``` Result: API = (141.5 / 0.85) - 131.5 ≈ 35.0° (medium gravity oil) **Note:** API gravity is the industry standard for oil classification. Use this conversion when you have specific gravity but need API gravity for correlations or reporting. """ api = oil.oil_api(sg_value=request.sg) # Convert numpy array to list for JSON serialization if isinstance(api, np.ndarray): value = api.tolist() else: value = float(api) return { "value": value, "method": "Standard conversion", "units": "degrees API", "inputs": request.model_dump(), }
- Pydantic BaseModel defining the input schema for the tool, with a validated 'sg' field supporting scalar or list inputs between 0 and 1.5.class SGConversionRequest(BaseModel): """Request model for SG to API conversion.""" sg: Union[float, List[float]] = Field( ..., description="Specific gravity - scalar or array" ) @field_validator("sg") @classmethod def validate_sg(cls, v): """Validate SG values.""" if isinstance(v, list): if not all(val > 0 and val < 1.5 for val in v): raise ValueError("Oil SG must be between 0 and 1.5") else: if v <= 0 or v >= 1.5: raise ValueError("Oil SG must be between 0 and 1.5") return v
- src/pyrestoolbox_mcp/server.py:16-30 (registration)Top-level registration where register_oil_tools(mcp) is called to register all oil tools, including 'oil_api_from_sg', to the FastMCP server instance.from .tools.oil_tools import register_oil_tools from .tools.gas_tools import register_gas_tools from .tools.inflow_tools import register_inflow_tools from .tools.simtools_tools import register_simtools_tools from .tools.brine_tools import register_brine_tools from .tools.layer_tools import register_layer_tools from .tools.library_tools import register_library_tools register_oil_tools(mcp) register_gas_tools(mcp) register_inflow_tools(mcp) register_simtools_tools(mcp) register_brine_tools(mcp) register_layer_tools(mcp) register_library_tools(mcp)
- src/pyrestoolbox_mcp/tools/oil_tools.py:27-27 (registration)The register_oil_tools function that defines and registers the oil_api_from_sg tool using the @mcp.tool() decorator inside the FastMCP instance.def register_oil_tools(mcp: FastMCP) -> None: