Mapping

[bocklund]

This (DRAFT) PR adds support for a new mapping system in PyCalphad, in the spirit of the algorithm published by Sundman et al.. This PR is the culmination of significant effort and much of the credit to getting it this close to the finish line goes to @nury12n

Features

1. The PR intends to add support for mapping and plotting:

• 1D stepping in axis variables (e.g. for property diagrams)
• Binary phase diagrams (to supersede the current binplot based on pycalphad.plot.binary.map)
• Ternary isothermal phase diagrams (to supersede the current ternplot based on eqplot)
• Isopleth diagrams

2. The visual quality of diagrams is significantly improved:

• Points on phase boundaries are now connected by solid lines
• Invariant reactions in binary phase diagrams are computed and drawn now
• Many pathological cases that gave previous algorithms trouble are resolved, including mapping regions that are very narrow with respect to the conditions, e.g. γ-loops and narrow liquidus/solidus regions.

3. Provides an API to programmatically access phase boundaries and phase equilibria computed by the mapping algorithm

4. In this PR, binplot and ternplot have drop-in replacements using the new mapping backend and those are now the default (we plan to keep support for the existing binplot and ternplot for backwards compatibility as the maturity of mapping improves).

Outstanding TODO items

On the current state of this PR:

• Currently binary phase diagrams work fairly well. Sometimes the solver fails to converge when one of the potentials (usually temperature) is not a condition and internal routines will give output ** On entry to DLASCLS parameter number 4 had an illegal value. I've seen this hang some Jupyter notebooks indefinitely, but plotting from a regular Python script from the command line seems to be a viable workaround.
• Stepping tends to work well as long as there are no miscibility gaps. With miscibility gaps, mapping can sometimes be flaky or find metastable phase equilibria, especially stepping from 1-phase to 2-phase MG regions.
• ternplot is working, but tends miss phase equilibria or produce metastable phase boundaries in systems with many stoichiometric compounds. See the Al-Cu-Y example.
• Isopleth support exists in principle, but isn't tested yet.

The examples are updated with the new binplot and tenrplot. The GitHub visual diff is helpful to see the state of things.

Concrete issues to fix beyond general stability and accuracy improvements

• Giving components to Mapper that do not include vacancies seems to produce silent failures where no boundaries are produced.
• Automated tests exercising the basic behavior to achieve coverage need to be implemented
• Mapper probably doesn't need to be a class. Simply a function is probably enough (this will presumably be called or adapted by Workspace down the line). That means StrategyBase becomes the common API, so we need to make sure that's clear.
• Needs a pep-8 pass. Specifically, variable names stick out as not very pycalphad-like. We should validate with something like Ruff: ruff check --select N,E7,E9,E4,F src
• Be more complete with binplot and ternplot API. e.g. missing x=, and y= arguments for ternplot.
• Any modules to remove/refactor/rename? (Specifically: utils.py, nobody likes utils.py)
• Resolve or workaround solver convergence issues when potentials are free (prevent T -> -inf). Conjecture: it’s impossible to have a stable solution when two or more phases have the same composition and there are no free potential conditions. This might be a root cause triggering the behavior. We should avoid proposing test equilibria in mapping when that’s the case. However, the only time we can guarantee two phases have exactly the same composition are for stoichometric phases. For the general case of any solution phase, we might simply want to make sure that we save for last testing exits where the newly added phase has the same composition as one of the phases we kept.

[bocklund]

Overall, I think this PR is in a state where it can be tested by users. Please report any bugs here.

[codecov]

Codecov Report

Attention: Patch coverage is 13.46479% with 1536 lines in your changes are missing coverage. Please review.

Project coverage is 76.23%. Comparing base (a5d051d) to head (059fbe0).
Report is 1 commits behind head on develop.

Files	Patch %	Lines
pycalphad/mapping/map_strategies/strategy_base.py	12.56%	320 Missing ⚠️
pycalphad/mapping/mapping.py	0.00%	246 Missing ⚠️
pycalphad/mapping/utils.py	9.59%	179 Missing ⚠️
pycalphad/mapping/primitives.py	31.52%	139 Missing ⚠️
...calphad/mapping/map_strategies/general_strategy.py	10.96%	138 Missing ⚠️
pycalphad/mapping/plotting.py	11.92%	133 Missing ⚠️
pycalphad/mapping/mapper.py	13.47%	122 Missing ⚠️
pycalphad/mapping/starting_points.py	14.04%	104 Missing ⚠️
pycalphad/mapping/map_strategies/step_strategy.py	16.86%	69 Missing ⚠️
...alphad/mapping/map_strategies/tielines_strategy.py	18.46%	53 Missing ⚠️
... and 1 more

Additional details and impacted files

@@             Coverage Diff              @@
##           develop     #517       +/-   ##
============================================
+ Coverage         0   76.23%   +76.23%     
============================================
  Files            0       62       +62     
  Lines            0     9641     +9641     
============================================
+ Hits             0     7350     +7350     
- Misses           0     2291     +2291     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[mfrichtl]

I'm a big fan of this PR. I have noticed there are occasionally regions where the tielines don't seem to be rendered correctly. An example from AL-C is shown below. This system is using assessments from Groebner (DOI: 10.1016/s0364-5916(96)00027-2) and Connetable (DOI: 10.1016/j.calphad.2008.01.002). The database file that I used to create this diagram is also attached.

AL-C.txt

[mfrichtl]

But if I run the binplot function with v.X('C'): (0, 1.01, 0.01), it seems to render the tielines.

[bocklund]

I'm a big fan of this PR. I have noticed there are occasionally regions where the tielines don't seem to be rendered correctly. An example from AL-C is shown below. This system is using assessments from Groebner (DOI: 10.1016/s0364-5916(96)00027-2) and Connetable (DOI: 10.1016/j.calphad.2008.01.002). The database file that I used to create this diagram is also attached.

AL-C.txt

Thanks, it's encouraging to hear you're finding it useful!

In the first plot is the mapping conditions for C (0, 1, 0.01)?

[mfrichtl]

@bocklund Yes, the first plot has the condition (0, 1, 0.01) for carbon.