Thermo refactor

[nury12n]

This pull request aims to refactor the thermodynamic, diffusion and precipitation modules. This is intended to reduce redundant code as well as make it easier for future development.

Changes to the thermodynamics module

• Reduce redundant code.
  • Driving force and multicomponent growth rate functions require computing equilibrium between the matrix and precipitate phase (either from global equilibrium or updating cached composition sets with new conditions) and performing some checks in case the precipitate phase becomes unstable or a miscibility gap appears. This will be done in a single function (GeneralThermodynamics._getCompositionSetsEq) and the driving force or multicomponent growth rate functions will just perform a few checks to validate the equilibrium calculations.
• Replace some of the larger tuple outputs with a named tuple. This should help with having to manage the outputs of some functions (eq. the curvature factors and growth rate functions in MulticomponentThermodynamics returned 5-6 values).
• Make use of certain python, pycalphad or numpy API to reduce the number of if or for blocks and hopefully make the code a bit shorter and more readable.
• setMobility and setDiffusivity will just take in a function (or dictionary of functions) that is only dependent on T.
  • This should make it easier if a user wants to set diffusivity outside of defining it in a TDB file.
  • Previous way of supplying a diffusivity model to PrecipitateModel was either defining it inside a TDB or defining it into the model. Now, the diffusivity will only be defined in a GeneralThermodynamics object.
  • Previous implementation in GeneralThermodynamics was to require the user to manually define functions that take in (v.GE, v.N, v.P, v.T, internal DOF). Any composition dependent mobilities or diffusivities should be defined in a TDB file from now on.

General changes in Diffusion and Precipitate models

• New framework will be in place where model parameters are separated from the model itself.
• The idea behind this is for all models to behave as Model(initial conditions, time, parameters) -> Results/Data
  • Users would be able to define parameters beforehand, then create multiple models the same parameters without having to redefine them
  • Results of the model will be in a single object that the user can pull out rather than being spread over multiple attributes in a model
• The intent for this new framework is mainly two-fold:
  • Make it easier perform computations that previously required a full model setup and some hacky method to extract these computations (ex. homogenization function and nucleation rate). With external model parameters, these functions can be used outside of a model (e.g. user will be allowed to plot the homogenization functions across composition or nucleation rate across temperature).
  • This should make development of new models easier
    • Ex. In future versions, the PrecipitateModel should be generalized to where the user can defined what theories to use for nucleation rate and growth rate calculations.
• Examples are updated to show the parameter framework.
• Models will take in a Thermodynamics object (or one with proper functions) as an input. Idea here would be that eventually, each model will require a certain protocol for the thermodynamic functions (e.g. requiring getDrivingForce or getInterdiffusivity, etc.) and the user will not be limited to using the built-in thermodynamic modules.

Changes to precipitation modeling

• ShapeFactor, NucleationBarrierParameters and StrainEnergy are refactored to follow a mediator like pattern:
  • The parameter itself will contain a "description" class which defines certain necessary functions. Then the functionality of the parameter would be to switch the "description" or evaluate some terms based on the "description".
  • Ex. In ShapeFactor, the descriptions are SphericalDescription, CubicDescription, PlateDescription and NeedleDescription which all defines the equivalent spherical radius, kinetic factors and thermodynamic factors
  • This will also allow for users to define they're own descriptions to test different theories

Changes in surrogate modeling

• The surrogate models is simplified and changed to allow for compatibility with the corresponding thermodynamic modules. In practice, a surrogate model can now model multiple phases and can be used in placement of thermodynamics in PrecipitateModel and SinglePhaseDiffusion models (HomogenizationModel does not yet support this). Because the surrogate is built from the thermodynamics module, any untrained model will fall back to the underlying thermodynamics function.
• Saving and loading are done through json instead of npy

Other changes

• Unit tests on the shape of outputs from the thermodynamic functions will also test for values
• Local phase conditions for sampling a precipitate composition as a starting point for computing driving force using the tangent (default) method. Right now, this is just an argument you can add when computing driving forces. In general, this is not needed, but I have encountered a case where I needed to provide a local phase condition as there was a negative curvature in the free energy function of the precipitate phase which threw off the driving force and precipitate composition.

API changes

• returnComp is removed from GeneralThermodynamics.getDrivingForce. These functions would always return a tuple regardless of the value of returnComp either as (driving force, precipitate comp) or (driving force, None). Now the driving force functions will always return (driving force, precipitate comp).
• 'GeneralThermodynamics.setDiffusivityis to be used in place ofPrecipitateModel.setDiffusivity`
• VolumeParameter is imported from kawin.precipitation.PrecipitationParameters

TODO

• Re-implement saving/loading
• Unit tests for the extra factors/parameters in precipitate module

[codecov]

Codecov Report

Attention: Patch coverage is 85.83806% with 474 lines in your changes missing coverage. Please review.

Project coverage is 81.08%. Comparing base (d2bb65c) to head (e121edf).
Report is 11 commits behind head on main.

Files with missing lines	Patch %	Lines
kawin/diffusion/DiffusionParameters.py	76.33%	80 Missing ⚠️
kawin/precipitation/parameters/ElasticFactors.py	85.95%	66 Missing ⚠️
kawin/thermo/Surrogate.py	88.02%	40 Missing ⚠️
kawin/precipitation/parameters/Nucleation.py	84.33%	39 Missing ⚠️
kawin/precipitation/NucleationRate.py	74.56%	29 Missing ⚠️
kawin/thermo/MultiTherm.py	79.23%	27 Missing ⚠️
kawin/diffusion/Diffusion.py	58.62%	24 Missing ⚠️
kawin/precipitation/KWNBase.py	82.17%	23 Missing ⚠️
kawin/precipitation/KWNEuler.py	85.71%	21 Missing ⚠️
kawin/precipitation/PrecipitationParameters.py	92.15%	16 Missing ⚠️
... and 14 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #11      +/-   ##
==========================================
+ Coverage   75.55%   81.08%   +5.52%     
==========================================
  Files          42       49       +7     
  Lines        6475     6660     +185     
==========================================
+ Hits         4892     5400     +508     
+ Misses       1583     1260     -323     

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