[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80987":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":12,"stars30d":14,"stars90d":13,"forks30d":13,"starsTrendScore":13,"compositeScore":15,"rankGlobal":8,"rankLanguage":8,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":8,"pushedAt":8,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":13,"starSnapshotCount":13,"syncStatus":14,"lastSyncTime":24,"discoverSource":25},80987,"Claude-for-reservoir-engineering","gabrielserrao\u002FClaude-for-reservoir-engineering","gabrielserrao",null,"Python",32,5,1,0,2,2.33,"MIT License",false,"main",true,[],"2026-06-12 02:04:09","# Claude for Reservoir Engineering\n\nA hands-on Claude Code course for reservoir engineers, production engineers, petroleum engineers, subsurface data scientists, and technical teams who want to use AI-assisted coding without giving up engineering rigor.\n\nThis repository teaches Claude Code through reservoir engineering tasks instead of generic toy examples. Every exercise is framed around workflows engineers actually recognize: production data QA, water-cut trends, PVT unit checks, decline curve analysis, material balance discipline, nodal-analysis prompts, black-oil simulation preparation, pyResToolbox usage, and Model Context Protocol (MCP) tools.\n\nThe goal is not to make Claude \"do engineering\" blindly. The goal is to teach engineers how to direct Claude like a disciplined technical assistant: give it context, constrain assumptions, require units, verify results, use tests, and prefer proven libraries or MCP tools over invented formulas.\n\n## Why This Course Exists\n\nReservoir engineering work is full of small but consequential details:\n\n- pressure units: psia vs barsa\n- temperature units: degF vs degC\n- gas gravity parameter names that change across APIs\n- correlations that are only valid in certain ranges\n- production forecasts that look smooth but violate simple sanity checks\n- material balance calculations that are only as good as their input history\n- simulation tables that must be traceable and reproducible\n\nAI tools can accelerate this work, but only when the engineer supplies enough domain context and demands verification. This course shows that workflow in concrete, repeatable exercises.\n\n## What You Will Learn\n\nBy the end of the course, you should be able to:\n\n- use Claude Code's explore, plan, code, and verify loop on engineering scripts\n- write prompts that identify the file, function, failing behavior, units, and expected engineering relationship\n- ask Claude to add tests with known values, monotonicity checks, and physical bounds\n- create and use `CLAUDE.md` project memory for reservoir-specific standards\n- package repeatable reservoir workflows as Claude skills\n- use a reviewer subagent to catch unit, assumption, and correlation mistakes\n- combine Claude with shell commands for production-data QA\n- use pyResToolbox and pyrestoolbox-mcp for reservoir calculations rather than hand-rolling correlations\n- parallelize independent sensitivity cases and aggregate the results carefully\n\n## Who This Is For\n\nThis course is designed for:\n\n- reservoir engineers learning AI-assisted coding\n- production engineers working with CSV exports and decline curves\n- petroleum engineering students who know the domain but want better coding workflows\n- data scientists supporting subsurface teams\n- technical managers evaluating Claude Code for engineering workflows\n- open-source contributors building reservoir engineering automation\n\nYou do not need to be a software engineer. You should be comfortable reading basic Python and using a terminal.\n\n## Source Inspiration\n\nThis project adapts the excellent exercise style of [`claude-code-for-hydrology`](https:\u002F\u002Fgithub.com\u002Florenliu13\u002Fclaude-code-for-hydrology) to reservoir engineering.\n\nIt is built around concepts and tooling from:\n\n- [`pyResToolbox`](https:\u002F\u002Fgithub.com\u002Fmwburgoyne\u002FpyResToolbox), a Python reservoir engineering utility library by Mark Burgoyne\n- [`pyrestoolbox-mcp`](https:\u002F\u002Fgithub.com\u002Fgabrielserrao\u002Fpyrestoolbox-mcp), an MCP server exposing pyResToolbox calculations to AI assistants\n- Claude Code workflows: project memory, skills, subagents, testing, MCP, and parallel work\n\n## Repository Structure\n\n```text\n.\n├── 01_explore_plan_code\u002F          # Production analysis: explore, plan, implement\n├── 02_specific_context\u002F           # PVT conversion bug: precise context beats vague prompts\n├── 03_verify_your_work\u002F           # DCA checks: tests and sanity checks\n├── 04_init_claude_md\u002F             # Project memory with CLAUDE.md\n├── 05_skills\u002F                     # Reservoir engineering Claude skills\n├── 06_subagent_review\u002F            # Reservoir reviewer subagent workflow\n├── 07_cli_workflow\u002F               # Shell + Python QA for production CSVs\n├── 08_mcp_pyrestoolbox\u002F           # Using pyResToolbox through MCP\n├── 09_parallel_fanout\u002F            # Parallel sensitivity studies\n├── assets\u002F                        # Generated plots and reference result tables\n├── scripts\u002Fgenerate_course_figures.py\n├── .claude\u002F\n│   ├── agents\u002Freservoir-reviewer.md\n│   └── skills\u002F\n│       ├── reservoir-engineering\u002FSKILL.md\n│       └── run-tests\u002FSKILL.md\n├── references\u002Fpyrestoolbox-workflows.md\n├── CLAUDE.md\n├── requirements.txt\n└── README.md\n```\n\n## Prerequisites\n\nInstall:\n\n- [Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code)\n- Python 3.10 or newer\n- `pip` or a Python environment manager\n- optional but recommended: `pyrestoolbox`\n- optional for live AI tool calls: [`pyrestoolbox-mcp`](https:\u002F\u002Fgithub.com\u002Fgabrielserrao\u002Fpyrestoolbox-mcp)\n\nClone the repository:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fgabrielserrao\u002FClaude-for-reservoir-engineering.git\ncd Claude-for-reservoir-engineering\n```\n\nInstall Python dependencies:\n\n```bash\npython3 -m pip install -r requirements.txt\n```\n\nIf your system uses `python` instead of `python3`, adjust the commands accordingly.\n\nGenerate the course plots and result tables:\n\n```bash\npython3 scripts\u002Fgenerate_course_figures.py\n```\n\nThe generated outputs live in `assets\u002F` and are committed so the course is readable on GitHub without running code first. Re-run the script whenever the sample data or screening assumptions change.\n\n## Quick Start\n\nOpen Claude Code from the repository root:\n\n```bash\nclaude\n```\n\nStart with Exercise 1:\n\n```bash\ncd 01_explore_plan_code\n```\n\nRead the exercise README, then try the \"before\" prompt and the \"after\" prompt. The contrast is the point of the course: you will see how much better Claude performs when you provide files, units, expected engineering behavior, and verification commands.\n\n## How Each Exercise Works\n\nEach exercise is self-contained and follows a consistent structure:\n\n1. Read the exercise README.\n2. Try the vague prompt first.\n3. Clear Claude's context with `\u002Fclear`.\n4. Try the improved prompt.\n5. Compare the results.\n6. Run the tests or checks.\n7. Reflect on what changed in the prompt and workflow.\n\nThe \"before\" prompts are intentionally under-specified. They mimic how engineers often start with an AI tool. The \"after\" prompts show the level of context and constraint that produces dependable technical work.\n\n## Course Modules\n\n| # | Folder | Claude Code Practice | Reservoir Engineering Focus |\n|---|--------|----------------------|-----------------------------|\n| 1 | `01_explore_plan_code\u002F` | Explore -> Plan -> Code | Production summary and water-cut trend analysis |\n| 2 | `02_specific_context\u002F` | Provide exact file\u002Ffunction\u002Fsymptom context | Fixing PVT unit-conversion behavior |\n| 3 | `03_verify_your_work\u002F` | Use tests as the quality gate | Exponential decline and EUR sanity checks |\n| 4 | `04_init_claude_md\u002F` | Create persistent project memory | Reservoir standards in `CLAUDE.md` |\n| 5 | `05_skills\u002F` | Encode repeatable domain workflows | Reservoir engineering skill usage |\n| 6 | `06_subagent_review\u002F` | Add a reviewer agent | Unit, assumption, and correlation review |\n| 7 | `07_cli_workflow\u002F` | Use shell tools and Python together | Production CSV QA before analysis |\n| 8 | `08_mcp_pyrestoolbox\u002F` | Use MCP tools for live calculations | pyResToolbox PVT and simulation workflows |\n| 9 | `09_parallel_fanout\u002F` | Parallelize independent cases | Sensitivity studies across methods and assumptions |\n\n## Illustrated Outputs\n\nThis course now includes generated figures that make the engineering checks visible. The purpose is not decoration. The plots show what Claude should be asked to produce or verify before an engineer trusts the result.\n\n![Production water-cut diagnostic](assets\u002Fproduction_water_cut.png)\n\nThe sample production data shows two simple but useful signals:\n\n- `A-01` has stronger oil volume but water cut still increases from 7.7% to 14.6%.\n- `B-02` starts wetter and also trends upward, from 21.6% to 27.7%.\n- A useful Claude prompt should ask for both the calculation and the interpretation: \"is water cut increasing, by how many percentage points, and does the trend respect well\u002Fdate ordering?\"\n\n![PVT API to specific gravity curve](assets\u002Fpvt_api_specific_gravity.png)\n\nPVT unit bugs are easier to catch when the expected relationship is visible. Higher API gravity means lighter oil, so specific gravity should decrease as API increases. A fix that passes a round-trip test but violates this monotonic relationship is still suspicious.\n\n![DCA decline sensitivity](assets\u002Fdca_decline_sensitivity.png)\n\nThe DCA plot makes two checks concrete:\n\n- Higher nominal decline should produce lower future rates for the same initial rate.\n- Lower economic limits should increase EUR, but the result is still a screening calculation, not a reserves booking.\n\n![Claude reservoir workflow](assets\u002Fclaude_reservoir_workflow.png)\n\nThe generated tables behind these figures are in `assets\u002Fgenerated_results.md`.\n\n## Exercise 1: Explore, Plan, Then Code\n\nClaude is most useful when it first understands the codebase. In this exercise, Claude reads a production analysis script, a sample production CSV, and existing tests before adding water-cut trend analysis.\n\nEngineering lesson:\n\n- Water cut must be computed from oil and water volumes.\n- The trend must respect well\u002Fdate ordering.\n- A production metric should be tested against known values.\n- A plot should reveal whether a calculation is plausible before anyone reads the code line by line.\n\nClaude lesson:\n\n- Plan mode reduces unnecessary edits.\n- File-specific prompts produce better implementations.\n- Tests define what \"done\" means.\n- Generated figures create a second verification surface: if the table says water cut rises but the plot falls, investigate.\n\n## Exercise 2: Specific Context\n\nSmall PVT conversion bugs are easy to miss and costly to propagate. This exercise shows how to tell Claude exactly which test fails and which petroleum engineering relationship applies.\n\nEngineering relationship:\n\n```text\nSG = 141.5 \u002F (API + 131.5)\nAPI = 141.5 \u002F SG - 131.5\n```\n\nInterpretation guardrail:\n\n- API and specific gravity move in opposite directions.\n- A 35 API oil has SG near 0.850.\n- The conversion is dimensionless; pressure conversion bugs should not be mixed into this function.\n\nClaude lesson:\n\n- \"Fix the PVT bug\" makes Claude search and guess.\n- Naming the failing test and expected formula lets Claude go directly to the fault.\n- Asking for monotonic checks catches a broader class of mistakes than one round-trip example.\n\n## Exercise 3: Verify Your Work\n\nDecline curve helpers can look plausible while hiding invalid assumptions. This exercise uses known values and sanity checks for exponential decline and EUR calculations.\n\nGood tests include:\n\n- known analytic values\n- nonnegative rates\n- rejected invalid inputs\n- EUR increasing as the economic limit decreases\n- sensitivity plots that make method and assumption choices obvious\n\nClaude lesson:\n\n- Ask for verification, not just implementation.\n- Give Claude a command to run after edits.\n- Make engineering checks explicit.\n\n## Exercise 4: Project Memory With CLAUDE.md\n\nReservoir engineering projects have recurring rules: units, method names, assumptions, validation, and output standards. `CLAUDE.md` keeps that context available across sessions.\n\nThis repository's root `CLAUDE.md` tells Claude to:\n\n- state field vs metric units\n- prefer pyResToolbox or MCP tools for standard calculations\n- avoid silent correlation changes\n- include tests or sanity checks for engineering functions\n- watch pyrestoolbox-mcp parameter naming conventions\n\nClaude lesson:\n\n- Persistent project memory prevents repeated explanations.\n- Domain-specific instructions improve every later prompt.\n\n## Exercise 5: Skills\n\nSkills package reusable instructions for common work. This repository includes a reservoir engineering skill and a test-running skill.\n\nThe reservoir engineering skill covers:\n\n- oil PVT\n- gas PVT\n- brine and CO2 workflows\n- DCA\n- material balance\n- nodal\u002FIPR\u002FVLP\n- relative permeability tables\n- simulation table preparation\n- parameter naming pitfalls in pyrestoolbox-mcp\n\nClaude lesson:\n\n- Do not paste the same domain rules into every prompt.\n- Use skills to keep high-value instructions close to the model.\n\n## Exercise 6: Subagent Review\n\nEngineering code benefits from an independent review pass. The included `reservoir-reviewer` agent checks for:\n\n- unit consistency\n- correlation applicability\n- nonphysical outputs\n- pyResToolbox or MCP parameter mistakes\n- missing tests\n- weak assumptions\n\nClaude lesson:\n\n- Use a reviewer for higher-risk work.\n- Ask for findings first, not praise or summaries.\n- Treat the review as a quality gate.\n\n## Exercise 7: CLI Workflow\n\nBefore fitting DCA models or running material balance, production data should be checked. This module uses Claude with shell commands and Python checks to inspect CSV data.\n\nTypical QA checks:\n\n- required columns exist\n- dates parse correctly\n- rates are nonnegative\n- well\u002Fdate rows are not duplicated\n- cumulative production is monotonic when expected\n\nClaude lesson:\n\n- Let Claude use the terminal to inspect real files.\n- Ask it to summarize evidence, not just assumptions.\n\n## Exercise 8: pyResToolbox MCP\n\nClaude should not invent industry correlations when reliable tools are available. This exercise shows how to ask Claude to use pyResToolbox through MCP for live reservoir engineering calculations.\n\nExample prompt:\n\n```text\nUse the pyResToolbox MCP tools.\nCalculate bubble point pressure for 35 API oil at 180 degF with solution GOR 800 scf\u002Fstb and gas gravity 0.75.\nUse Valko-McCain if available.\nState units, method, inputs, and one sanity check.\n```\n\nImportant pyrestoolbox-mcp reminders:\n\n- oil tools usually use `sg_g` for gas gravity\n- gas tools usually use `sg`\n- inflow tools use `psd` for sandface pressure\n- some gas tools use `zmethod`, not `method`\n- relative permeability table types include `SWOF`, `SGOF`, and `SGWFN`\n\nClaude lesson:\n\n- Use MCP tools when you need live calculations.\n- Ask for inputs, units, method, output, and sanity check every time.\n\n## Exercise 9: Parallel Fan-Out\n\nSensitivity cases are often independent. Claude can split them across workers or parallel calls, then aggregate the results.\n\nExample independent cases:\n\n- bubble point methods: `STAN`, `VALMC`, `VELAR`\n- gas Z-factor methods: `DAK`, `HY`, `WYW`\n- skin cases: `-2`, `0`, `5`\n\nClaude lesson:\n\n- Parallelize independent scenarios only.\n- Require each worker to return assumptions and units.\n- Use a final aggregation step to compare results.\n\n## Running Tests\n\nRun all tests:\n\n```bash\npython3 -m pytest -v\n```\n\nRun one exercise:\n\n```bash\npython3 -m pytest 01_explore_plan_code\u002F -v\n```\n\nThe tests are intentionally small. They are teaching tools, not a complete engineering validation suite. When adapting the patterns to real work, add more edge cases, known-value comparisons, and domain-specific acceptance criteria.\n\n## Using pyResToolbox\n\nInstall pyResToolbox:\n\n```bash\npython3 -m pip install pyrestoolbox\n```\n\nExample:\n\n```python\nfrom pyrestoolbox import oil\n\npbub = oil.oil_pbub(\n    api=35,\n    degf=180,\n    rsb=800,\n    sg_g=0.75,\n    pbmethod=\"VALMC\",\n)\n\nprint(pbub)\n```\n\nWhen using pyResToolbox directly, always capture:\n\n- input values and units\n- method\u002Fcorrelation name\n- output units\n- applicability assumptions\n- simple sanity checks\n\n## Using pyrestoolbox-mcp\n\nFor Claude Desktop or another MCP-capable assistant, use:\n\n```text\nhttps:\u002F\u002Fgithub.com\u002Fgabrielserrao\u002Fpyrestoolbox-mcp\n```\n\nThat project exposes pyResToolbox calculations as MCP tools so Claude can call reservoir engineering functions directly.\n\nRecommended response format for MCP-backed calculations:\n\n```text\nInputs:\n- API gravity: ...\n- reservoir temperature: ...\n- pressure: ...\n\nMethod:\n- correlation\u002Ftool used: ...\n\nResult:\n- value and units: ...\n\nSanity check:\n- physical or engineering check: ...\n\nAssumptions:\n- ...\n```\n\n## Included Claude Assets\n\nThis repository includes Claude configuration examples:\n\n- `.claude\u002Fskills\u002Freservoir-engineering\u002FSKILL.md`\n- `.claude\u002Fskills\u002Frun-tests\u002FSKILL.md`\n- `.claude\u002Fagents\u002Freservoir-reviewer.md`\n- `.claude\u002Fsettings.json`\n- `CLAUDE.md`\n\nThese are meant to be studied and adapted. The most important pattern is not the exact wording. The important pattern is that reservoir engineering constraints are made explicit and reusable.\n\n## Generated Figures\n\nThe course figures are built from `scripts\u002Fgenerate_course_figures.py`. This script intentionally uses small, transparent calculations:\n\n- water cut and GOR from `01_explore_plan_code\u002Fsample_production.csv`\n- API-to-specific-gravity reference points from the standard petroleum engineering relationship\n- exponential decline screening cases with explicit `qi`, `di`, and economic-limit assumptions\n- a workflow diagram showing the intended Claude Code quality loop\n\nTo refresh the figures:\n\n```bash\npython3 scripts\u002Fgenerate_course_figures.py\n```\n\nThen review `assets\u002Fgenerated_results.md` and the PNGs before committing. If a figure changes, the narrative should change with it.\n\n## Suggested Teaching Format\n\nFor a workshop or internal training session:\n\n1. Spend 10 minutes introducing Claude Code and the repository.\n2. Run Exercise 1 as a live demo.\n3. Have participants do Exercises 2 and 3 individually.\n4. Discuss how each prompt changed Claude's behavior.\n5. Show `CLAUDE.md`, skills, and the reviewer agent.\n6. Demonstrate an MCP-backed pyResToolbox calculation.\n7. Finish with the parallel fan-out exercise.\n\nExpected workshop duration: 90 to 150 minutes.\n\n## Engineering Standards Used In This Course\n\nEvery serious reservoir engineering prompt should include:\n\n- units\n- method or correlation\n- input ranges\n- expected output shape\n- validation criteria\n- assumptions\n- whether field or metric units are being used\n- whether the answer is screening-level or decision-grade\n\nEvery serious engineering code change should include:\n\n- focused tests\n- known-value checks where possible\n- nonphysical input handling\n- output bounds or monotonicity checks where appropriate\n- clear file\u002Ffunction scope\n\n## Limitations\n\nThis course is educational. The sample data is fictional and intentionally small. The examples are designed to teach Claude Code workflows, not to certify engineering calculations.\n\nFor real reservoir decisions:\n\n- validate against company standards\n- check correlation applicability\n- peer review material calculations\n- document assumptions\n- compare against independent tools where appropriate\n- do not use AI output as the sole technical basis for field decisions\n\n## Contributing\n\nContributions are welcome, especially:\n\n- new reservoir engineering exercises\n- better tests with known petroleum engineering values\n- pyResToolbox or pyrestoolbox-mcp workflow examples\n- additional Claude skills or reviewer agents\n- teaching notes for classroom or workshop use\n- fixes to units, terminology, or engineering assumptions\n\nSuggested contribution pattern:\n\n1. Add a numbered exercise folder.\n2. Include a `README.md` with before\u002Fafter prompts.\n3. Include a small Python file or workflow artifact.\n4. Include focused tests or validation instructions.\n5. Keep sample data fictional or openly licensed.\n\n## License\n\nThis project is intended to be open sourced as a course. See `LICENSE` for details.\n\n## Acknowledgements\n\nThanks to the maintainers and contributors of:\n\n- Claude Code and the Claude ecosystem\n- pyResToolbox\n- pyrestoolbox-mcp\n- claude-code-for-hydrology\n","该项目是一个面向储层工程师、生产工程师、石油工程师、地下数据科学家及其技术团队的实践课程，旨在教授如何使用Claude Code进行AI辅助编程而不牺牲工程严谨性。核心功能包括通过实际工程任务（如生产数据质量保证、含水率趋势分析、PVT单位检查等）来学习Claude Code的应用，并强调在使用AI工具时提供足够的领域背景信息和验证结果的重要性。此外，课程还涵盖了编写有效提示词、添加测试用例、创建项目记忆文件等内容。适合于希望提升编码效率同时保持专业标准的储层相关从业者，特别是那些熟悉Python基础并愿意探索自动化工作流程的专业人士。","2026-06-11 04:03:06","CREATED_QUERY"]