alfasim-score 1.4.0

Features

• Converter from Score input JSON to Alfacase

• Converter from Wellprop pvt tables to .tab pvt table format

• Parser for the ALFAsim results and generate a JSON compatible with SCORE

• Checker and fixer for .tab pvt tables that have zeroed properties for phases that do not exist

How to use it

1. First, the user needs to create an instance of the converter:

   from pathlib import Path
   from alfasim_score.converter.alfacase.alfasim_score_converter import AlfasimScoreConverter
   # path indicating where the SCORE input file is
   score_input_filepath = Path("path/to/score_input.json")
   # path indicating where the output file (converted from ALFAsim results) should be created
   score_output_filepath = Path("path/to/score_output_result.json")
   # then create a converter instance
   alfacase_converter = AlfasimScoreConverter(score_input_filepath, score_output_filepath)

2. To convert the SCORE input into an alfacase file, the user can do the following:

   alfacase_filepath = Path("path/where/save/converted_score.alfacase")
   alfacase_converter.generate_alfasim_input_file(alfacase_filepath)

3. Run the ALFAsim with the generated file (and the pvt tables in the same folder)

4. Once the result file of ALFAsim is generated, one can call the converter for the output file:

   alfasim_results_directory = Path("path/to/alfasim_results_folder")
   alfacase_converter.generate_score_output_file(alfasim_results_directory)

5. The user also must remember to convert and save the pvt table (as .tab file) if wellprop tables are being used:

   from alfasim_score.converter.wellprop.wellprop_pvt_table_converter import WellpropToPvtConverter
   table_converter = WellpropToPvtConverter(Path("name_of_folder_with_wellprop_tables"))
   table_converter.generate_pvt_table_file(Path("name_of_folder_to_save_converted_pvt_table"))

   The saved table is already fixed, so the phases that do not exist in the wellprop csv files do not reach ALFAsim as zeroed properties.

6. The pvt tables delivered by WELLBOREPROPS as .tab files write every property as zero where a phase does not exist, which ALFAsim is not able to use. These tables can be checked and fixed with:

   from alfasim_score.converter.pvt_table.pvt_table_fixer import PvtTableFixer
   fixer = PvtTableFixer.from_file(Path("DFLT_BLACK_OIL_27.40_230.00_1.17.tab"))
   print(fixer.check().describe())
   fixer.generate_fixed_pvt_table_file(Path("DFLT_BLACK_OIL_27.40_230.00_1.17_fixed.tab"))

   The properties of the points where the phase does not exist are filled with the values of the closest point where it does exist (at the same temperature first, then at the same pressure). When the phase does not exist anywhere in the table, its properties are copied from the other phase. The gas mass fraction is never changed, so a filled phase keeps the fraction zero and is never actually used by ALFAsim.

   The same is available in the command line, where --check-only reports the problems without writing any file and exits with 1 when the table has to be fixed:

   $ alfasim-score-fix-pvt-table --check-only DFLT_BLACK_OIL_27.40_230.00_1.17.tab
   $ alfasim-score-fix-pvt-table DFLT_BLACK_OIL_27.40_230.00_1.17.tab

Development

For complete description of what type of contributions are possible, see the full CONTRIBUTING guide.

Here is a quick summary of the steps necessary to setup your environment to contribute to alfasim-score.

1. Create a virtual environment and activate it:

   $ python -m virtualenv .env
   $ .env\Scripts\activate  # windows
   $ source .env/bin/activate  # linux

2. Update pip:

   $ python -m pip install -U pip

3. Install development dependencies:

   $ pip install -e .[testing]

4. Install pre-commit:

   $ pre-commit install

5. Run tests:

   $ pytest --pyargs alfasim_score

6. Generate docs locally:

   $ tox -e docs

   The documentation files will be generated in docs/_build.

Release

A reminder for the maintainers on how to make a new release.

Note that the VERSION should folow the semantic versioning as X.Y.Z Ex.: v1.0.5

1. Create a release-VERSION branch from upstream/master.

2. Update CHANGELOG.rst.

3. Push a branch with the changes.

4. Once all builds pass, push a VERSION tag to upstream. Ex: git tag v1.0.5; git push origin --tags

5. Merge the PR.

1.4.0 (2026-08-03)

• Include script and CLI (alfasim-score-fix-pvt-table) to check and fix .tab PVT tables delivered by WELLBOREPROPS that write zeroed properties for phases that do not exist.

• Fix wellbore/node PVT model on the converted alfacase to use the base PVT table.

1.3.1 (2026-06-19)

• Update alfasim-sdk dependency to 1.6.0 and migrate to the generate_alfacase_file API.

• Drop support for Python 3.8 and 3.9 (alfasim-sdk requires Python >= 3.10).

1.2.1 (2026-06-19)

• Fix output results JSON dropping annuli MDs beyond the annulus end and emitting volume.diff as a scalar.

1.2.0 (2026-06-10)

• Include support to simulation regime input.

1.1.1 (2026-03-19)

• Ignore walls with NaN or negative dummy values from ALFAsim output to build output results JSON layers.

1.1.0 (2026-02-20)

• Update the alfacase converter to support ALFAsim APB plugin v2025.2.1

• Update convert to improve ALFAsim simulation performance: * Use Zamora correlation for PVT table input * Periodic calculation for APB * Update of thermal properties only in initalization

1.0.0 (2025-04-11)

• Update the alfacase converter to create files compatible with ALFAsim APB plugin v1.0.1

• Add new converter for pvt tables from wellprops to .tab format

0.2.0 (2024-12-18)

• Improvements on API.

• Add documentation on how to use the API.

0.1.0 (2024-06-10)

• First release on PyPI.