Skip to content

ENH: Add Component implementation in variables#546

Merged
bocklund merged 18 commits intopycalphad:developfrom
bocklund:complex-components
Aug 8, 2024
Merged

ENH: Add Component implementation in variables#546
bocklund merged 18 commits intopycalphad:developfrom
bocklund:complex-components

Conversation

@bocklund
Copy link
Copy Markdown
Collaborator

@bocklund bocklund commented Jul 14, 2024

This PR sets the groundwork for more formally distinguishing a Component from a Species. It is breaking for the public API of Workspace, and consumers of the private API for pycalphad.core.utils.unpack_components. We are making these breaking changes now, so future changes that implement generalized (non-pure-element) component support can be non-breaking or minimally breaking in public APIs.

The following changes are made:

  1. Add v.Component class. This is similar to Species, but distinct because 1) Species are reserved to refer to phase constituents, and 2) Species are allowed to have charges
  2. Rename pycalphad.core.utils.unpack_components to unpack_species to be more accurate
  3. Add a v.unpack_components function to process components following documented rules comparable to those in commercial software packages
  4. Modify Workspace API:
    4.1. Rename Workspace.components, which is a container of Species, objects to Workspace.constituents. Workspace.constituents automatically update when Workspace.components change. Currently the constituents are not used in the Workspace implementation and changes from users don't affect any calculations, but it might be possible to use this to suspend certain species.
    4.2. Add ComponentsList and ComponentsField implementations Workspace, as a container of Component objects in Workspace.components with the ability to auto-populate from Database pure elements and update when the database changes.

What is not in this PR is explicit support for non-pure element components as a basis for use in conditions, properties, etc. Non-pure element components is a driver for the Component object to exist, but support is not added here.

@bocklund bocklund added the workspace Issues related to the Workspace feature label Jul 14, 2024
@bocklund
Copy link
Copy Markdown
Collaborator Author

bocklund commented Jul 15, 2024

Conceptually, this PR seeks to add the left hand side of this diagram. Before this PR, PyCalphad only uses pure elements as the composition basis set

ComponentsVennDiagram

note that vacancies are sort of special. TDBs treat vacancies as an Element, but they are probably better categorized as a Species (== phase constituent), as they aren't part of the composition basis, like a Component. For now, we will continue to treat them as Component objects, which is backwards-compatible conceptually. But eventually I think it makes sense to not treat them as components, but purely as a constituent

@bocklund
Copy link
Copy Markdown
Collaborator Author

I think there's value to trying to get something merged that has v.Component support without necessarily having any linear combination stuff implemented for non-pure element v.Component instances.

as_property also has at least some limited LinearCombination support, so getting something like v.MU(v.Component("AB2")) does produce a linear combination of MU(A) + 2*MU(B) (which isn't right for the chemical potentials, which should be normalized per mole)

@codecov
Copy link
Copy Markdown

codecov bot commented Jul 17, 2024

Codecov Report

Attention: Patch coverage is 97.81421% with 4 lines in your changes missing coverage. Please review.

Project coverage is 91.97%. Comparing base (aa84469) to head (7a53130).

Files Patch % Lines
pycalphad/variables.py 95.60% 4 Missing ⚠️
Additional details and impacted files
@@             Coverage Diff             @@
##           develop     #546      +/-   ##
===========================================
+ Coverage    91.83%   91.97%   +0.13%     
===========================================
  Files           77       77              
  Lines        12121    12270     +149     
===========================================
+ Hits         11131    11285     +154     
+ Misses         990      985       -5     

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

@bocklund
Copy link
Copy Markdown
Collaborator Author

Given the context of just getting something in, I'm ready for some feedback @richardotis

I'm not entirely happy with how things are done. Maybe we need a ComponentBase or something. Separating the semantics of Species := PhaseConstituents and Component := CompositionBasis throughout all of the variables isn't done here yet, but I think the types are mostly correct.

There's probably further distinction to make in _expand_property_arguments between properties that are composition-dependent and should be using Component, and properties that are site fraction-dependent, and should be using Species. I guess the heuristic now is that hasattr(sublattice_index) is True only for things that should be Species. Using species.name or component.name to check for wildcards should be fine I think.

@bocklund
Copy link
Copy Markdown
Collaborator Author

bocklund commented Jul 17, 2024

The final version of this PR should close #226, (edit: fixing #226 is considered out of scope for this PR) which will require some changes to the API documentation and variables, and overall just thinking through the legacy code and whether it makes sense to take in Component or take in Species as the argument, and which to use inside each function/object, and make sure the corresponding calls to unpack_components or unpack_species is called.

If we're in the breaking spirit, I am also open to feedback on the renaming the current Species object to PhaseConstituent (or just Constitutient) and unpack_species to unpack_phase_constituents (or unpack_constituents). Maybe that would enable the class heirarchy to be

class Species(object):
    ...

class Component(Species):
    ...

class PhaseConstituent(Species):
   ...
# or 
class Constituent(Species):
   ...

@bocklund bocklund force-pushed the complex-components branch from b044399 to c00632a Compare August 7, 2024 05:21
@bocklund bocklund marked this pull request as ready for review August 8, 2024 16:31
@bocklund bocklund changed the title Support generalized components ENH: Add Component implementation in variables Aug 8, 2024
@bocklund bocklund requested a review from richardotis August 8, 2024 16:50
@bocklund bocklund merged commit 94457b9 into pycalphad:develop Aug 8, 2024
@bocklund bocklund deleted the complex-components branch August 8, 2024 18:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

workspace Issues related to the Workspace feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants