Metadata-Version: 2.4
Name: alfasim-score
Version: 1.4.0
Summary: Python package to convert the SCORE input JSON to Alfacase
Home-page: https://github.com/ESSS/alfasim-score
Author: ESSS
Author-email: foss@esss.co
License: MIT license
Keywords: ALFAsim,Score
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
License-File: LICENSE
Requires-Dist: alfasim-sdk==1.6.0
Requires-Dist: attrs>=18.1.0
Requires-Dist: numpy>=1.11.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: oop-ext>=1.1
Requires-Dist: typing_extensions
Provides-Extra: testing
Requires-Dist: codecov; extra == "testing"
Requires-Dist: mypy; extra == "testing"
Requires-Dist: pre-commit; extra == "testing"
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-cov; extra == "testing"
Requires-Dist: pytest-mock; extra == "testing"
Requires-Dist: pytest-regressions; extra == "testing"
Requires-Dist: tox; extra == "testing"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

===============
ALFAsim Score
===============


.. image:: https://img.shields.io/pypi/v/alfasim-score.svg
    :target: https://pypi.python.org/pypi/alfasim-score

.. image:: https://img.shields.io/pypi/pyversions/alfasim-score.svg
    :target: https://pypi.org/project/alfasim-score

.. image:: https://github.com/ESSS/alfasim-score/workflows/test/badge.svg
    :target: https://github.com/ESSS/alfasim-score/actions

.. image:: https://codecov.io/gh/ESSS/alfasim-score/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/ESSS/alfasim-score

.. image:: https://img.shields.io/readthedocs/alfasim-score.svg
    :target: https://alfasim-score.readthedocs.io/en/latest/

.. image:: https://sonarcloud.io/api/project_badges/measure?project=ESSS_alfasim-score&metric=alert_status
    :target: https://sonarcloud.io/project/overview?id=ESSS_alfasim-score


What is alfasim-score?
=======================

Python package to convert the SCORE input JSON to Alfacase (ALFAsim input file).


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
-------------
#. 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)

#. 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)

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

#. 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)

#. 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.

#. 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 <CONTRIBUTING.rst>`_ guide.

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

#. Create a virtual environment and activate it::

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


   .. note::

       If you use ``conda``, you can install ``virtualenv`` in the root environment::

           $ conda install -n root virtualenv

       Don't worry as this is safe to do.

#. Update ``pip``::

    $ python -m pip install -U pip

#. Install development dependencies::

    $ pip install -e .[testing]

#. Install pre-commit::

    $ pre-commit install

#. Run tests::

    $ pytest --pyargs alfasim_score

#. 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.


.. _`GitHub page` :                   https://github.com/ESSS/alfasim-score
.. _pytest:                           https://github.com/pytest-dev/pytest
.. _tox:                              https://github.com/tox-dev/tox


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.
