Metadata-Version: 2.4
Name: factsage-compound
Version: 0.1.1
Summary: Tools for reading and working with FactSage compound database files.
Keywords: factsage,chemapp,thermodynamics,materials-science
Author: Eugene Nekhoroshev
Author-email: evgnekhoroshev@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: numpy (>=1.23)
Requires-Dist: pandas (>=2.0)
Requires-Dist: pyparsing (>=3.1)
Requires-Dist: xlwings (>=0.24)
Project-URL: Documentation, https://evnekdev.github.io/factsage-compound-docs/
Project-URL: Homepage, https://github.com/evnekdev/factsage-compound
Project-URL: Repository, https://github.com/evnekdev/factsage-compound
Description-Content-Type: text/markdown

# Wiki project for Compound Database files (not part of the official FactSage distribution, written by Dr Evgenii Nekhoroshev)

The detailed documentation on the internal workings of the FactSage Compound Database file format is located at:

[FactSage Compound Database Project](https://evnekdev.github.io/factsage-compound-docs/)

# factsage-compound

`factsage-compound` is a Python package for reading, inspecting, and editing FactSage Compound Database (`.CDB`) files.

It parses the fixed-width binary chunk format used by FactSage compound databases and exposes Python objects for:

- loading a database into memory
- iterating through compounds and phases
- inspecting thermodynamic values and heat-capacity ranges
- editing selected values in memory
- saving the modified binary back to disk

## Features

- Parses FactSage compound database chunks into structured NumPy-backed objects
- Provides object wrappers for `Database`, `Compound`, `Phase`, and `Range`
- Supports lookup by formula, compound name, and ChemApp-style phase labels
- Preserves binary layout so modified databases can be written back to disk

## Installation from PyPI

From a command window, run

```cmd
pip install factsage-compound
```

## Installation from the repository (if the PyPI distribution not available)

To install `factsage-compound` from the GitHub repository at [factsage-compound](https://github.com/evnekdev/factsage-compound), use

```cmd
git clone https://github.com/evnekdev/factsage-compound
```

and later run the installation from inside the cloned directory using `poetry` tool (```pip install poetry```):

```cmd
poetry install
```

`poetry` tool automatically builds a wheel and installs it into your current Python directory (a valid Python installation must exist on your computer, of course).

## Quick start (Excel interface, database comparison)

If you already installed `factsage-compound`, `xlwings` package should be already installed as a requirement.

Locate the `xlwings` addin in `$PYTHONPATH\Lib\site-packages\xlwings\addin` through Excel File -> Options -> Add-ins (Manage Excel Addins, Go) interface. If everything goes ok, an `xlwings` tab appears in the top Excel Ribbon.

In File -> Options -> Trust Center -> Trust Center Settings -> Macro Settings set "Enable VBA macros" toggle button and "Enable Excel 4.0 macros when VBA macros are enabled" and "Trust access to the VBA project object model" ticks.

You can download an xlsm templates from [Excel Template](examples/Template.xlsm).

If you create your own xlsm book from scratch, you will need an xlwings.conf sheet with the following contents:

| | A | B |
|---|---|---|
|1| Interpreter_Win | $PYTHONPATH\python.exe |
|2| Interpreter_Mac |                        |
|3| PYTHONPATH      |                        |
|4| Conda Path      |                        |
|5| Conda Env       |                        |
|6| UDF Modules     | factsage_compound      |
|7| Debug UDFs      | FALSE                  |
|8| Use UDF Server  | TRUE                   |
|9| Show Console    | TRUE                   |


## Quick start (pure Python)

```python
from factsage_compound import Database

# Load an existing FactSage compound database
db = Database("SENDBASE.CDB")

print(f"Compounds: {len(db.compounds)}")

# Find a compound and inspect its phases
compound = db.find_compound_by_formula("FeO")
if compound is not None:
    print(compound.name)
    for phase in compound.phases:
        print(phase.label, phase.name)
```

## Data model

### Database

`Database` loads the binary `.CDB` file and parses it into a list of `Compound` objects.

Useful methods:

- `save()` writes the current in-memory chunk array back to the original file
- `find_compound_by_formula(formula)` returns the first matching compound
- `find_compound_by_name(name)` returns the first compound whose name starts with the provided text
- `find_phase_by_chemapp_name(name)` resolves a ChemApp-style identifier and returns the matching phase

### Compound

`Compound` wraps a compound chunk and collects associated phases, heat-capacity ranges, and comments.

Useful attributes and methods:

- `name`: human-readable compound name
- `formula`: formula string stored in the file
- `coefficients_real`: real stoichiometric coefficients array
- `phases`: list of `Phase` instances
- `find_phase_by_name(name)`
- `find_phase_by_label_chemapp(label)`

### Phase

`Phase` represents one thermodynamic phase of a compound.

Useful attributes:

- `name`
- `density`
- `state` (`S`, `L`, `G`, or `Aq`)
- `index`
- `label`
- `label_chemapp`
- `ranges`
- `kappas`

For non-transition phases (`chunk_id == CHUNK_TYPE_PHASE1`):

- `enthalpy`
- `entropy`

For transition phases (`chunk_id == CHUNK_TYPE_PHASE2`):

- `transition_enthalpy`
- `transition_temperature`

### Range

`Range` stores heat-capacity coefficients for a temperature interval.

Useful attributes:

- `coefficients`
- `powers`
- `t_min`
- `t_max`
- `enthalpy`
- `entropy`

## Example workflows

### Find a phase by ChemApp label

```python
from factsage_compound import Database

db = Database("SENDBASE.CDB")
phase = db.find_phase_by_chemapp_name("FeO_wustite(s)")

if phase:
    print(phase.name)
    print(phase.label_chemapp)
```

### Update thermodynamic values and save

```python
from factsage_compound import Database

db = Database("SENDBASE.CDB")
compound = db.find_compound_by_formula("FeO")
phase = compound.find_phase_by_name("Wustite")

if phase and not phase.has_transition():
    phase.enthalpy = phase.enthalpy + 100.0
    phase.entropy = phase.entropy + 0.1

 db.save()
```

