generate_black_oil_table
Generate comprehensive black oil PVT tables for reservoir simulation and analysis, calculating key properties like solution gas-oil ratio, formation volume factor, and viscosity across pressure ranges.
Instructions
Generate comprehensive black oil PVT table.
COMPREHENSIVE PVT TABLE GENERATOR - Creates complete black oil PVT table with all properties (Rs, Bo, μo, ρo, Co) at pressures from 14.7 psia to specified maximum. This is the most comprehensive PVT tool, generating complete tables for reservoir simulation input or analysis. Optionally exports ECLIPSE-compatible keywords.
Parameters:
pi (float, required): Initial reservoir pressure in psia. Must be > 0. Example: 4000.0. Table starts from 14.7 psia and goes up to pmax.
api (float, required): Oil API gravity in degrees. Valid: 0-100. Example: 38.0.
degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000. Example: 175.0.
sg_g (float, required): Gas specific gravity (air=1). Valid: 0-3. Typical: 0.6-1.2. Example: 0.68.
pmax (float, optional, default=0.0): Maximum pressure for table in psia. If 0, auto-calculates as pi × 1.5. Must be > pi. Example: 5000.0.
pb (float, optional, default=0.0): Bubble point pressure in psia. If 0, will be calculated. Example: 3900.0.
rsb (float, optional, default=0.0): Solution GOR at bubble point in scf/stb. If 0, will be calculated. Example: 2300.0.
nrows (int, optional, default=50): Number of table rows. Valid: 1-200. More rows = finer resolution. Typical: 20-100. Example: 50.
export (bool, optional, default=False): Export ECLIPSE-compatible files. If True, creates PVTO.INC, PVDO.INC, DENSITY.INC files. Example: False.
pb_method (str, optional, default="VALMC"): Bubble point method. Options: "STAN", "VALMC", "VELAR". VALMC recommended.
rs_method (str, optional, default="VELAR"): Solution GOR method. Options: "VELAR", "STAN", "VALMC". VELAR recommended.
bo_method (str, optional, default="MCAIN"): Oil FVF method. Options: "MCAIN", "STAN". MCAIN recommended.
uo_method (str, optional, default="BR"): Oil viscosity method. Only "BR" available.
Generated Properties:
Rs: Solution gas-oil ratio (scf/stb) - increases with pressure up to pb
Bo: Formation volume factor (rb/stb) - peaks at bubble point
μo: Oil viscosity (cP) - minimum at bubble point
ρo: Oil density (lb/cuft) - calculated from mass balance
Co: Oil compressibility (1/psi) - increases near bubble point
Table Structure: Pressure values are logarithmically spaced from 14.7 psia to pmax, with finer spacing near bubble point for accuracy.
ECLIPSE Export: When export=True, generates:
PVTO.INC: Pressure-dependent oil properties (for undersaturated oil)
PVDO.INC: Dead oil properties (for heavy oils)
DENSITY.INC: Oil density table
Returns: Dictionary with:
table (list of dicts): PVT table data, each dict contains pressure and all properties
summary (dict): Key values (bubble point, rsb, Bob, μob, etc.)
columns (list): Column names in table
methods (dict): Methods used for each property
export_files (dict, optional): File names if export=True
inputs (dict): Echo of input parameters
Common Mistakes:
Setting pmax too low (should be > pi for complete table)
Not providing pb and rsb when known (reduces accuracy)
Using wrong correlation methods (use recommended defaults)
Too few rows (nrows < 20) causing poor resolution
Not understanding table format for simulation input
Example Usage:
Result: Complete PVT table with 50 rows covering 14.7-5000 psia with all properties.
Note: This is the most comprehensive PVT tool. Use for complete reservoir analysis or simulation input preparation. Always provide pb and rsb when available for best accuracy. For simulation, set export=True to generate ECLIPSE keywords.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Implementation Reference
- Main handler function for the 'generate_black_oil_table' tool. Decorated with @mcp.tool() and implements the logic by calling pyrestoolbox.oil.make_bot_og to generate the PVT table and formats the response.@mcp.tool() def generate_black_oil_table(request: BlackOilTableRequest) -> dict: """Generate comprehensive black oil PVT table. **COMPREHENSIVE PVT TABLE GENERATOR** - Creates complete black oil PVT table with all properties (Rs, Bo, μo, ρo, Co) at pressures from 14.7 psia to specified maximum. This is the most comprehensive PVT tool, generating complete tables for reservoir simulation input or analysis. Optionally exports ECLIPSE-compatible keywords. **Parameters:** - **pi** (float, required): Initial reservoir pressure in psia. Must be > 0. Example: 4000.0. Table starts from 14.7 psia and goes up to pmax. - **api** (float, required): Oil API gravity in degrees. Valid: 0-100. Example: 38.0. - **degf** (float, required): Reservoir temperature in °F. Valid: -460 to 1000. Example: 175.0. - **sg_g** (float, required): Gas specific gravity (air=1). Valid: 0-3. Typical: 0.6-1.2. Example: 0.68. - **pmax** (float, optional, default=0.0): Maximum pressure for table in psia. If 0, auto-calculates as pi × 1.5. Must be > pi. Example: 5000.0. - **pb** (float, optional, default=0.0): Bubble point pressure in psia. If 0, will be calculated. Example: 3900.0. - **rsb** (float, optional, default=0.0): Solution GOR at bubble point in scf/stb. If 0, will be calculated. Example: 2300.0. - **nrows** (int, optional, default=50): Number of table rows. Valid: 1-200. More rows = finer resolution. Typical: 20-100. Example: 50. - **export** (bool, optional, default=False): Export ECLIPSE-compatible files. If True, creates PVTO.INC, PVDO.INC, DENSITY.INC files. Example: False. - **pb_method** (str, optional, default="VALMC"): Bubble point method. Options: "STAN", "VALMC", "VELAR". VALMC recommended. - **rs_method** (str, optional, default="VELAR"): Solution GOR method. Options: "VELAR", "STAN", "VALMC". VELAR recommended. - **bo_method** (str, optional, default="MCAIN"): Oil FVF method. Options: "MCAIN", "STAN". MCAIN recommended. - **uo_method** (str, optional, default="BR"): Oil viscosity method. Only "BR" available. **Generated Properties:** - **Rs**: Solution gas-oil ratio (scf/stb) - increases with pressure up to pb - **Bo**: Formation volume factor (rb/stb) - peaks at bubble point - **μo**: Oil viscosity (cP) - minimum at bubble point - **ρo**: Oil density (lb/cuft) - calculated from mass balance - **Co**: Oil compressibility (1/psi) - increases near bubble point **Table Structure:** Pressure values are logarithmically spaced from 14.7 psia to pmax, with finer spacing near bubble point for accuracy. **ECLIPSE Export:** When export=True, generates: - **PVTO.INC**: Pressure-dependent oil properties (for undersaturated oil) - **PVDO.INC**: Dead oil properties (for heavy oils) - **DENSITY.INC**: Oil density table **Returns:** Dictionary with: - **table** (list of dicts): PVT table data, each dict contains pressure and all properties - **summary** (dict): Key values (bubble point, rsb, Bob, μob, etc.) - **columns** (list): Column names in table - **methods** (dict): Methods used for each property - **export_files** (dict, optional): File names if export=True - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Setting pmax too low (should be > pi for complete table) - Not providing pb and rsb when known (reduces accuracy) - Using wrong correlation methods (use recommended defaults) - Too few rows (nrows < 20) causing poor resolution - Not understanding table format for simulation input **Example Usage:** ```python { "pi": 4000.0, "api": 38.0, "degf": 175.0, "sg_g": 0.68, "pmax": 5000.0, "pb": 3900.0, "rsb": 2300.0, "nrows": 50, "export": False, "pb_method": "VALMC", "rs_method": "VELAR", "bo_method": "MCAIN", "uo_method": "BR" } ``` Result: Complete PVT table with 50 rows covering 14.7-5000 psia with all properties. **Note:** This is the most comprehensive PVT tool. Use for complete reservoir analysis or simulation input preparation. Always provide pb and rsb when available for best accuracy. For simulation, set export=True to generate ECLIPSE keywords. """ result = oil.make_bot_og( pi=request.pi, api=request.api, degf=request.degf, sg_g=request.sg_g, pmax=request.pmax if request.pmax > 0 else request.pi * 1.5, pb=request.pb, rsb=request.rsb, nrows=request.nrows, export=request.export, pbmethod=request.pb_method, rsmethod=request.rs_method, bomethod=request.bo_method, ) # Convert DataFrame to list of dicts table_data = result["bot"].to_dict(orient="records") response = { "table": table_data, "summary": { "bubble_point_psia": float(result.get("pb", 0)), "solution_gor_scf_stb": float(result.get("rsb", 0)), "oil_fvf_at_pb_rb_stb": float(result.get("bob", result.get("Bo", 1.0))), "oil_viscosity_at_pb_cp": float(result.get("uob", result.get("uo", 1.0))), "oil_density_at_pb_lb_cuft": float(result.get("deno_oil", result.get("den", 50.0))), "gas_sg": float(result.get("sg_sp", result.get("sg_g", 0.75))), "rows": len(table_data), }, "columns": list(result["bot"].columns), "methods": { "pb_method": request.pb_method, "rs_method": request.rs_method, "bo_method": request.bo_method, "uo_method": request.uo_method, }, "inputs": request.model_dump(), } if request.export: response["export_files"] = { "pvto_file": "PVTO.INC", "pvdo_file": "PVDO.INC", "density_file": "DENSITY.INC", "note": "Files exported to current working directory", } return response
- Pydantic model defining the input parameters and validation rules for the generate_black_oil_table tool.class BlackOilTableRequest(BaseModel): """Request model for black oil table generation.""" model_config = ConfigDict( json_schema_extra={ "example": { "pi": 4000.0, "api": 38.0, "degf": 175.0, "sg_g": 0.68, "pmax": 5000.0, "pb": 3900.0, "rsb": 2300.0, "nrows": 50, } } ) pi: float = Field(..., gt=0, description="Initial reservoir pressure (psia)") api: float = Field(..., gt=0, le=100, description="Oil API gravity (degrees)") degf: float = Field( ..., gt=-460, lt=1000, description="Temperature (degrees Fahrenheit)") sg_g: float = Field( ..., ge=0, le=3, description="Gas specific gravity (air=1, dimensionless)") pmax: float = Field( 0.0, ge=0, description="Maximum pressure for table (psia, 0=auto)") pb: float = Field(0.0, ge=0, description="Bubble point pressure (psia, 0=calculate)") rsb: float = Field( 0.0, ge=0, description="Solution GOR at bubble point (scf/stb, 0=calculate)") nrows: int = Field(50, gt=0, le=200, description="Number of table rows") export: bool = Field(False, description="Export ECLIPSE-compatible files") pb_method: Literal["STAN", "VALMC", "VELAR"] = Field( "VALMC", description="Bubble point calculation method") rs_method: Literal["VELAR", "STAN", "VALMC"] = Field( "VELAR", description="Solution GOR method") bo_method: Literal["MCAIN", "STAN"] = Field( "MCAIN", description="Oil FVF method") uo_method: Literal["BR"] = Field("BR", description="Oil viscosity method")
- src/pyrestoolbox_mcp/server.py:16-24 (registration)Explicit registration of the oil tools (including generate_black_oil_table) 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)
- src/pyrestoolbox_mcp/tools/oil_tools.py:27-30 (registration)The register_oil_tools function that defines and registers all oil tools via @mcp.tool() decorators.def register_oil_tools(mcp: FastMCP) -> None: """Register all oil-related tools with the MCP server.""" @mcp.tool()