NeqSim Project Structure Recommendations

This document provides actionable recommendations to improve the NeqSim project structure, addressing clarity, discoverability, and maintainability.

1. Root Directory Organization

Current State

Recommendations

A. Group Configuration Files

Create a .config/ directory for build/formatting configurations:

mkdir .config
git mv checkstyle_neqsim.xml .config/
git mv eclipse-java-google-style.xml .config/
git mv neqsim_formatter.xml .config/
git mv settings.xml .config/

Update references in:

B. Group POM Variants

Current: pom.xml, pomJava8.xml, pomJava21.xml, dependency-reduced-pom.xml all at root

Recommendation: Add a README_POMS.md at root explaining:

# POM Files in NeqSim

- **pom.xml** - Main build file (Java 8 target, Maven 3.6+)
- **pomJava8.xml** - Java 8 explicit profile (CI/legacy builds)
- **pomJava21.xml** - Java 21 testing profile (internal only, not published)
- **dependency-reduced-pom.xml** - Generated by maven-shade-plugin (do not edit)

For normal development, use `pom.xml` only. See docs/development/BUILD.md for details.

C. Document Cleanup Scripts

Issue: Root has scripts like _update_report.py without clear documentation

Recommendation: Create scripts/ directory:

mkdir scripts
git mv _update_report.py scripts/

Add scripts/README.md:

# Scripts Directory

- **update_report.py** - Regenerate metrics badges for README.md
  - Usage: `python scripts/update_report.py`
  - Run after: Security/dependency updates

See individual script headers for usage details.

2. AI Agent Organization

Current State

Recommendations

A. Consolidate Duplicate Agents

Check if these are duplicates and merge:

Action:

# Compare content
diff .github/agents/process.model.agent.md .github/agents/processmodel.agent.md

# If identical or mergeable, keep one canonical name
git mv .github/agents/processmodel.agent.md .github/agents/process.model.agent.md

B. Agent Naming Convention

Establish consistent naming: <domain>.<action>.agent.md

Recommended renames:

✓ Good: solve.task.agent.md, thermo.fluid.agent.md
✓ Good: flow.assurance.agent.md, gas.quality.agent.md
✓ Rename: processmodel.agent.md → process.model.agent.md

C. Reduce Documentation Duplication

Current: AGENTS.md (root) and .github/copilot-instructions.md share large sections

Recommendation: Single-source principle

  1. Keep AGENTS.md as external-facing (for OpenAI Codex, Claude, standalone agents)
  2. Keep .github/copilot-instructions.md as VS Code Copilot-specific (tool restrictions, UI patterns)
  3. Extract shared content to docs/development/AI_AGENT_REFERENCE.md:
    • Code patterns
    • Java 8 compatibility rules
    • API verification rules
    • JavaDoc standards

Then both files import the reference:

<!-- In AGENTS.md -->
## Code Patterns
See [AI Agent Reference](docs/development/AI_AGENT_REFERENCE.md#code-patterns) for copy-paste starters.

<!-- In .github/copilot-instructions.md -->
<instructions>
Include: docs/development/AI_AGENT_REFERENCE.md
</instructions>

D. Agent Index File

Create .github/agents/README.md:

# NeqSim Copilot Agents

This directory contains specialized GitHub Copilot Chat agents for NeqSim development.

## Available Agents

| Agent | Command | Purpose |
|-------|---------|---------|
| **solve.task** | `@solve.task <description>` | End-to-end task solving with report generation |
| **thermo.fluid** | `@thermo.fluid <description>` | Create thermodynamic fluid systems |
| **process.model** | `@process.model <description>` | Build process simulations |
| **pvt.simulation** | `@pvt.simulation <description>` | Run PVT lab tests (CME, CVD, DL) |
| **flow.assurance** | `@flow.assurance <description>` | Hydrate, wax, asphaltene, corrosion |
| **gas.quality** | `@gas.quality <description>` | ISO 6976, sales specs, gas quality |
| **mechanical.design** | `@mechanical.design <description>` | ASME/API/DNV mechanical design |
| **safety.depressuring** | `@safety.depressuring <description>` | Blowdown, PSV sizing, fire case |
| **neqsim.test** | `@neqsim.test <description>` | Create JUnit 5 unit tests |
| **notebook.example** | `@notebook.example <description>` | Create Jupyter notebook examples |
| **documentation** | `@documentation <description>` | Write/update markdown docs |

## Usage

In VS Code Copilot Chat:

@solve.task 3-stage compression with intercooling from 5 to 150 bara


See the [AGENTS.md](../../AGENTS.md) file in the repo root for detailed documentation.

3. Examples Directory Structure

Current State

examples/
├── CNGtankmodelling/     # Single-task folder
├── neqsim/              # Generic folder (unclear purpose)
├── notebooks/           # 28+ mixed notebooks
└── sulfurtask/          # Single-task folder

Recommendations

A. Reorganize by Category

Create topical subdirectories for better discoverability:

examples/
├── README.md                           # NEW - index of all examples
├── notebooks/
│   ├── 01_quickstart/                  # NEW - beginner examples
│   │   ├── 01_first_flash.ipynb
│   │   ├── 02_simple_separator.ipynb
│   │   └── README.md
│   ├── 02_thermodynamics/              # NEW - thermo examples
│   │   ├── phase_envelope.ipynb
│   │   ├── hydrate_prediction.ipynb
│   │   └── README.md
│   ├── 03_process_simulation/          # NEW - process examples
│   │   ├── teg_dehydration.ipynb
│   │   ├── compression_train.ipynb
│   │   └── README.md
│   ├── 04_pvt_analysis/                # NEW - PVT examples
│   │   ├── cme_test.ipynb
│   │   ├── cvd_test.ipynb
│   │   └── README.md
│   ├── 05_field_development/           # NEW - subsea/field dev
│   │   ├── subsea_tieback.ipynb
│   │   ├── well_design.ipynb
│   │   └── README.md
│   ├── 06_standards/                   # NEW - standards examples
│   │   ├── iso6976_calorific_value.ipynb
│   │   └── README.md
│   └── 07_advanced/                    # NEW - advanced topics
│       ├── custom_eos.ipynb
│       └── README.md
├── java/                               # NEW - standalone Java examples
│   ├── quickstart/
│   │   ├── FirstFlash.java
│   │   └── README.md
│   ├── process/
│   │   ├── TEGDehydrationExample.java
│   │   └── README.md
│   └── pvt/
│       └── CMETestExample.java
└── case_studies/                       # RENAMED from CNGtankmodelling, sulfurtask
    ├── cng_tank_thermal_analysis/      # RENAMED
    │   └── README.md
    └── sulfur_deposition/              # RENAMED
        └── README.md

B. Create Examples Index

Create examples/README.md:

# NeqSim Examples

This directory contains Jupyter notebooks, Java examples, and case studies demonstrating NeqSim capabilities.

## Quick Start (5 minutes)
- [First TPflash](notebooks/01_quickstart/01_first_flash.ipynb) - Your first fluid calculation
- [Simple Separator](notebooks/01_quickstart/02_simple_separator.ipynb) - Basic process equipment

## By Topic

### Thermodynamics
- Phase envelopes, flash calculations, physical properties
- See [notebooks/02_thermodynamics/](notebooks/02_thermodynamics/)

### Process Simulation
- Separators, compressors, heat exchangers, complete flowsheets
- See [notebooks/03_process_simulation/](notebooks/03_process_simulation/)

### PVT Analysis
- CME, CVD, differential liberation, swelling tests
- See [notebooks/04_pvt_analysis/](notebooks/04_pvt_analysis/)

### Field Development
- Subsea wells, pipelines, SURF cost estimation
- See [notebooks/05_field_development/](notebooks/05_field_development/)

### Standards & Compliance
- ISO 6976 calorific values, gas quality specifications
- See [notebooks/06_standards/](notebooks/06_standards/)

## Java Examples
Standalone Java programs you can copy-paste into your projects:
- [java/quickstart/](java/quickstart/) - Getting started
- [java/process/](java/process/) - Process simulation
- [java/pvt/](java/pvt/) - PVT calculations

## Case Studies
Complete worked examples from real projects:
- [CNG Tank Thermal Analysis](case_studies/cng_tank_thermal_analysis/)
- [Sulfur Deposition in Gas Pipelines](case_studies/sulfur_deposition/)

See also:
- [Documentation Examples](../docs/examples/) - Documentation-embedded examples
- [Test Examples](https://github.com/equinor/neqsim/tree/master/src/test/java/neqsim/) - Unit test examples

4. Task Solve Directory

Current State

Recommendations

A. Add Cleanup Documentation

Create task_solve/README.md section:

## Housekeeping

The `task_solve/` directory is gitignored (your local work area). Clean it periodically:

### After Completing a Task
1. **Promote reusable outputs** to the main repo:
   - Tests → `src/test/java/neqsim/`
   - Notebooks → `examples/notebooks/`
   - Docs → Appropriate docs/ subfolder
   - Add task log entry → `docs/development/TASK_LOG.md`

2. **Archive or delete the task folder**:
   - Keep if ongoing or reference needed
   - Delete if outputs promoted and no longer needed

### Cleanup Old Tasks
```powershell
# List tasks older than 30 days
Get-ChildItem task_solve -Directory | Where-Object {$_.CreationTime -lt (Get-Date).AddDays(-30)}

# Archive to task_solve/archive/
New-Item -ItemType Directory -Path task_solve/archive -Force
Get-ChildItem task_solve -Directory | Where-Object {$_.CreationTime -lt (Get-Date).AddDays(-30)} | Move-Item -Destination task_solve/archive/

# Or delete completed tasks
Get-ChildItem task_solve -Directory -Exclude "TASK_TEMPLATE","archive" | Remove-Item -Recurse


#### B. Add Size Monitoring
Add to `devtools/new_task.py`:

```python
def check_task_solve_size():
    """Warn if task_solve/ exceeds 1GB"""
    task_dir = Path("task_solve")
    if not task_dir.exists():
        return

    total_size = sum(f.stat().st_size for f in task_dir.rglob('*') if f.is_file())
    size_gb = total_size / (1024**3)

    if size_gb > 1.0:
        print(f"\n⚠️  Warning: task_solve/ is {size_gb:.2f}GB")
        print("Consider archiving or deleting old tasks:")
        print("  See task_solve/README.md for cleanup instructions\n")

5. Documentation Structure

Current State

Recommendations

A. Clarify Documentation Purpose

Add to docs/README.md:

# Documentation Structure

NeqSim documentation is organized by **purpose and audience**:

## By Audience

| Directory | Audience | Content Type |
|-----------|----------|--------------|
| `quickstart/` | **New users** | 5-minute getting started guides |
| `tutorials/` | **Learning** | Step-by-step hands-on tutorials (30-120 min) |
| `examples/` | **Reference** | Short code snippets showing specific features |
| `wiki/` | **Concepts** | Explanatory articles on how things work |
| `development/` | **Contributors** | Developer guides, patterns, workflows |
| `manual/` | **API Reference** | Generated API documentation |

## By Topic
- `thermo/` - Thermodynamics and equations of state
- `process/` - Process equipment and flowsheets
- `pvtsimulation/` - PVT lab tests
- `standards/` - Industry standards (ISO, API, NORSOK)
- `fielddevelopment/` - Subsea, wells, field economics
- `troubleshooting/` - Common issues and solutions

## Finding What You Need
1. **New to NeqSim?** → Start with [quickstart/index.md](quickstart/index.md)
2. **Want to learn X?** → Check [tutorials/index.md](tutorials/index.md)
3. **Need code for Y?** → Search [examples/](examples/) or GitHub grep
4. **Understand concept Z?** → Read [wiki/](wiki/)
5. **Contributing code?** → Follow [development/](development/)

For a complete file index, see [REFERENCE_MANUAL_INDEX.md](REFERENCE_MANUAL_INDEX.md).

B. Deprecate or Merge Overlapping Content

Audit these for overlaps:

6. Test Organization

Current State

Recommendations

A. Add Test Documentation

Create src/test/java/neqsim/README.md:

# NeqSim Test Suite

This directory contains JUnit 5 unit tests mirroring the production code structure.

## Organization

Tests are organized to match `src/main/java/neqsim/`:

src/test/java/neqsim/ ├── NeqSimTest.java # Base test class (all tests extend this) ├── thermo/ # Thermodynamics tests ├── process/ # Process equipment tests ├── pvtsimulation/ # PVT test simulations ├── standards/ # Standards compliance tests └── … # Other packages


## Running Tests

```bash
# All tests
./mvnw test

# Single test class
./mvnw test -Dtest=SeparatorTest

# Single test method
./mvnw test -Dtest=SeparatorTest#testTwoPhase

# Exclude slow tests (default)
./mvnw test

# Include slow tests
./mvnw test -DexcludedTestGroups=

Writing Tests

  1. Extend NeqSimTest: All tests should extend this base class
  2. Mirror package structure: Place tests in the same package as the code under test
  3. Test naming: <ClassName>Test.java (e.g., SeparatorTest.java)
  4. Method naming: Descriptive test names (e.g., testTwoPhaseFlashWithWater())

See the wiki test overview for detailed testing guidelines.


#### B. Tag Slow Tests Consistently
Ensure all tests >10 seconds are tagged:

```java
@Tag("slow")
@Test
void testLongRunningSimulation() {
    // ...
}

7. Build Configuration Clarity

Current State

Recommendations

A. Create Build Reference

Create docs/development/BUILD.md:

# Building NeqSim

## Quick Commands

```powershell
# Windows
.\mvnw.cmd clean install      # Full build
.\mvnw.cmd test              # Tests only
.\mvnw.cmd package -DskipTests  # JAR without tests

# Linux/Mac
./mvnw clean install
./mvnw test
./mvnw package -DskipTests

Maven Wrapper

NeqSim uses Maven Wrapper (mvnw/mvnw.cmd) for consistent builds across environments.

Advantages:

POM Files Explained

File Purpose
pom.xml Main build file (use this for all development)
pomJava8.xml Java 8 compatibility testing profile
pomJava21.xml Java 21 testing profile (internal experiments)
dependency-reduced-pom.xml Auto-generated by shade plugin (do not edit)

Normal development uses pom.xml only.

Build Profiles

# Default (Java 8 target)
./mvnw install

# Skip tests
./mvnw install -DskipTests

# Include slow tests
./mvnw test -DexcludedTestGroups=

# Static analysis
./mvnw checkstyle:check spotbugs:check pmd:check

Troubleshooting

Build fails with “package does not exist”:

Tests fail intermittently:

JAR not updating in Python:

.\mvnw.cmd package -DskipTests
Copy-Item target\neqsim-3.5.0.jar $env:APPDATA\Python\Python312\site-packages\neqsim\lib\java11\ -Force

See CONTRIBUTING.md for code style and formatting setup.


#### B. Consolidate Build Commands
Update `CONTEXT.md` to reference `docs/development/BUILD.md`:

```markdown
## Build & Test (30 seconds)

See [docs/development/BUILD.md](docs/development/BUILD.md) for complete build reference.

Quick commands:
```powershell
.\mvnw.cmd install               # Full build
.\mvnw.cmd test -Dtest=SeparatorTest  # Single test class

8. Developer Onboarding Path

Current Issue

Recommendation: Create Developer Journey Map

Create docs/development/GETTING_STARTED_DEVELOPER.md:

# Getting Started as a NeqSim Developer

**Goal**: From `git clone` to first contribution in 30 minutes.

## Step 1: Environment Setup (5 min)

### Prerequisites
- Java 8+ (JDK, not just JRE)
- Git
- (Optional) VS Code with Java extensions

### Clone and Build
```bash
git clone https://github.com/equinor/neqsim.git
cd neqsim
./mvnw clean install    # First build (downloads deps, ~2 min)
./mvnw test             # Verify tests pass

Troubleshooting: See BUILD.md

Step 2: Understand Project Structure (10 min)

Read in order:

  1. CONTEXT.md - 60-second repo overview
  2. modules.md - Package architecture
  3. This file - Developer-specific workflows

Key directories:

src/main/java/neqsim/    # Production code
src/test/java/neqsim/    # Unit tests (mirrors main/)
docs/                    # Documentation
examples/notebooks/      # Jupyter examples
task_solve/              # Your local work area (gitignored)

Step 3: Pick Your Path (choose one)

A. Fix a Bug or Add Feature

  1. Check GitHub Issues
  2. Comment on the issue to claim it
  3. Create a branch: git checkout -b fix/issue-123
  4. Make changes following CODE_PATTERNS.md
  5. Add tests (mirror structure in src/test/)
  6. Submit PR using template

B. Solve an Engineering Task

  1. Use AI workflow: TASK_SOLVING_GUIDE.md
  2. Or manually: neqsim new-task "Your task description"
  3. Work through steps 1-3 in task_solve/<your_task>/
  4. Promote useful outputs to main repo

C. Write Documentation

  1. Find gaps or errors in docs/
  2. Use AI agent: @documentation in Copilot Chat
  3. Follow documentation agent guidelines
  4. Update REFERENCE_MANUAL_INDEX.md

D. Add Examples

  1. Create Jupyter notebook or Java example
  2. Follow notebook agent pattern
  3. Add to examples/ in appropriate category
  4. Update examples/README.md

Step 4: Code Style and Validation

Format Code (automatic in VS Code)

Settings in CONTRIBUTING.md

Before Committing

# Run checks
./mvnw checkstyle:check spotbugs:check pmd:check

# Run tests
./mvnw test

# If you modified documentation
cd docs && python generate_manual.py

Step 5: Submit Your Contribution

  1. Push branch: git push -u origin your-branch-name
  2. Create PR: Use GitHub UI or gh pr create
  3. Fill template: Include:
    • What changed
    • Why (link to issue if applicable)
    • Testing performed
    • Docs updated (if relevant)
  4. Respond to reviews: CI runs tests, reviewers check code
  5. Merge: After approval, squash & merge

Common Workflows

Update Your Branch

git fetch origin
git rebase origin/master    # Or merge if you prefer

Run Specific Tests

./mvnw test -Dtest=SeparatorTest#testTwoPhase

Debug in IDE

Getting Help

Next Steps

Implementation Priority

Implement in this order for maximum impact:

Phase 1: Documentation (Low Risk, High Value)

  1. ✅ Create examples/README.md index
  2. ✅ Create docs/development/BUILD.md
  3. ✅ Create docs/development/GETTING_STARTED_DEVELOPER.md
  4. ✅ Add task_solve/README.md cleanup section
  5. ✅ Add .github/agents/README.md index

Phase 2: File Reorganization (Medium Risk)

  1. ✅ Create .config/ and move config files (update refs in pom.xml, CONTRIBUTING.md)
  2. ✅ Create scripts/ and move utility scripts
  3. ✅ Consolidate duplicate agents (check content first)
  4. ✅ Reorganize examples/notebooks/ into categorized folders

Phase 3: Content Consolidation (Higher Risk)

  1. ✅ Extract shared content to docs/development/AI_AGENT_REFERENCE.md
  2. ✅ Update AGENTS.md and .github/copilot-instructions.md to reference it
  3. ✅ Audit and merge overlapping docs (wiki vs quickstart)

Success Metrics

After implementation, validate improvements:

Maintenance

Once structure is improved:

  1. Document in CONTRIBUTING.md: “Where to put new files”
  2. Add to PR template: Checklist for updating relevant READMEs
  3. Quarterly review: Check task_solve/ size, examples/ organization
  4. Update this doc: As new patterns emerge

Questions or suggestions? Open a GitHub Discussion.