gliquid 0.3.3__tar.gz → 0.3.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. {gliquid-0.3.3 → gliquid-0.3.4}/CHANGELOG.md +138 -1
  2. {gliquid-0.3.3 → gliquid-0.3.4}/CITATION.cff +2 -2
  3. {gliquid-0.3.3 → gliquid-0.3.4}/PKG-INFO +1 -1
  4. {gliquid-0.3.3 → gliquid-0.3.4}/notebooks/GaRu_adjustment.ipynb +1 -1
  5. {gliquid-0.3.3 → gliquid-0.3.4}/notebooks/PbTb_adjustment.ipynb +1 -1
  6. {gliquid-0.3.3 → gliquid-0.3.4}/notebooks/colab_demo.ipynb +1 -1
  7. {gliquid-0.3.3 → gliquid-0.3.4}/notebooks/fitting_demo.ipynb +1 -1
  8. {gliquid-0.3.3 → gliquid-0.3.4}/notebooks/interpolation_demo.ipynb +1 -1
  9. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/_version.py +2 -2
  10. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/binary.py +12 -3
  11. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/hsx.py +12 -5
  12. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/imputation/__init__.py +1 -0
  13. gliquid-0.3.4/src/gliquid/imputation/entry_list.py +245 -0
  14. gliquid-0.3.4/src/gliquid/imputation/ternary_imputation.py +908 -0
  15. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/liquidus_sheets.py +142 -78
  16. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/mpds.py +13 -2
  17. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/plotting/binary_tx.py +31 -10
  18. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/plotting/liquidus_fields.py +490 -126
  19. gliquid-0.3.4/src/gliquid/plotting/solidus_view.py +309 -0
  20. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/plotting/style.py +8 -0
  21. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/plotting/ternary_surface.py +31 -9
  22. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/reference/phase_transitions.json +15 -11
  23. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/solution.py +5 -4
  24. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/ternary.py +503 -25
  25. gliquid-0.3.3/src/gliquid/imputation/ternary_imputation.py +0 -549
  26. {gliquid-0.3.3 → gliquid-0.3.4}/.gitattributes +0 -0
  27. {gliquid-0.3.3 → gliquid-0.3.4}/.githooks/pre-commit +0 -0
  28. {gliquid-0.3.3 → gliquid-0.3.4}/.github/CODEOWNERS +0 -0
  29. {gliquid-0.3.3 → gliquid-0.3.4}/.github/dependabot.yml +0 -0
  30. {gliquid-0.3.3 → gliquid-0.3.4}/.github/workflows/release.yml +0 -0
  31. {gliquid-0.3.3 → gliquid-0.3.4}/.github/workflows/tests.yml +0 -0
  32. {gliquid-0.3.3 → gliquid-0.3.4}/.gitignore +0 -0
  33. {gliquid-0.3.3 → gliquid-0.3.4}/CONTRIBUTING.md +0 -0
  34. {gliquid-0.3.3 → gliquid-0.3.4}/LICENSE +0 -0
  35. {gliquid-0.3.3 → gliquid-0.3.4}/README.md +0 -0
  36. {gliquid-0.3.3 → gliquid-0.3.4}/assets/digitized_pd_anatomy.png +0 -0
  37. {gliquid-0.3.3 → gliquid-0.3.4}/assets/gliq_logo_tall.png +0 -0
  38. {gliquid-0.3.3 → gliquid-0.3.4}/assets/invariant_points_and_reactions.png +0 -0
  39. {gliquid-0.3.3 → gliquid-0.3.4}/assets/ru_si_assessed_pd.png +0 -0
  40. {gliquid-0.3.3 → gliquid-0.3.4}/conftest.py +0 -0
  41. {gliquid-0.3.3 → gliquid-0.3.4}/pyproject.toml +0 -0
  42. {gliquid-0.3.3 → gliquid-0.3.4}/requirements/min-constraints.txt +0 -0
  43. {gliquid-0.3.3 → gliquid-0.3.4}/scripts/run_colab_notebook.py +0 -0
  44. {gliquid-0.3.3 → gliquid-0.3.4}/scripts/run_notebooks.py +0 -0
  45. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/__init__.py +0 -0
  46. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/api.py +0 -0
  47. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/cache.py +0 -0
  48. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/config.py +0 -0
  49. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/hull_editor.py +0 -0
  50. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/imputation/ablation.py +0 -0
  51. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/imputation/binary_imputation.py +0 -0
  52. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/imputation/core.py +0 -0
  53. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/imputation/lifecycle.py +0 -0
  54. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/.gitkeep +0 -0
  55. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/feature_names.json +0 -0
  56. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/features_antisymmetric.json +0 -0
  57. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/features_symmetric.json +0 -0
  58. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/manifest.json +0 -0
  59. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_0/L0_a.ubj +0 -0
  60. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_0/L0_b.ubj +0 -0
  61. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_0/L1_a.ubj +0 -0
  62. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_0/best_params.json +0 -0
  63. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_0/metadata.json +0 -0
  64. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_0/model_summary.txt +0 -0
  65. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_0/preprocess.json +0 -0
  66. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_10/L0_a.ubj +0 -0
  67. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_10/L0_b.ubj +0 -0
  68. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_10/L1_a.ubj +0 -0
  69. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_10/best_params.json +0 -0
  70. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_10/metadata.json +0 -0
  71. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_10/model_summary.txt +0 -0
  72. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_10/preprocess.json +0 -0
  73. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_20/L0_a.ubj +0 -0
  74. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_20/L0_b.ubj +0 -0
  75. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_20/L1_a.ubj +0 -0
  76. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_20/best_params.json +0 -0
  77. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_20/metadata.json +0 -0
  78. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_20/model_summary.txt +0 -0
  79. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_20/preprocess.json +0 -0
  80. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_30/L0_a.ubj +0 -0
  81. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_30/L0_b.ubj +0 -0
  82. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_30/L1_a.ubj +0 -0
  83. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_30/best_params.json +0 -0
  84. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_30/metadata.json +0 -0
  85. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_30/model_summary.txt +0 -0
  86. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_30/preprocess.json +0 -0
  87. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_42/L0_a.ubj +0 -0
  88. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_42/L0_b.ubj +0 -0
  89. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_42/L1_a.ubj +0 -0
  90. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_42/best_params.json +0 -0
  91. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_42/metadata.json +0 -0
  92. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_42/model_summary.txt +0 -0
  93. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_42/preprocess.json +0 -0
  94. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_50/L0_a.ubj +0 -0
  95. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_50/L0_b.ubj +0 -0
  96. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_50/L1_a.ubj +0 -0
  97. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_50/best_params.json +0 -0
  98. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_50/metadata.json +0 -0
  99. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_50/model_summary.txt +0 -0
  100. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_50/preprocess.json +0 -0
  101. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_60/L0_a.ubj +0 -0
  102. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_60/L0_b.ubj +0 -0
  103. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_60/L1_a.ubj +0 -0
  104. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_60/best_params.json +0 -0
  105. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_60/metadata.json +0 -0
  106. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_60/model_summary.txt +0 -0
  107. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_60/preprocess.json +0 -0
  108. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_70/L0_a.ubj +0 -0
  109. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_70/L0_b.ubj +0 -0
  110. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_70/L1_a.ubj +0 -0
  111. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_70/best_params.json +0 -0
  112. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_70/metadata.json +0 -0
  113. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_70/model_summary.txt +0 -0
  114. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/models/20261028_105725/seed_70/preprocess.json +0 -0
  115. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/phase.py +0 -0
  116. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/plotting/__init__.py +0 -0
  117. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/plotting/binary_figs.py +0 -0
  118. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/plotting/export.py +0 -0
  119. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/plotting/phase_highlight.py +0 -0
  120. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/plotting/ternary_labels.py +0 -0
  121. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/plotting/ternary_projection.py +0 -0
  122. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/production_model_runner.py +0 -0
  123. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/reference/omegas_hcp.json +0 -0
  124. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/reference/spurious_structures.json +0 -0
  125. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/shap_compat.py +0 -0
  126. {gliquid-0.3.3 → gliquid-0.3.4}/src/gliquid/solid_coverage.py +0 -0
  127. {gliquid-0.3.3 → gliquid-0.3.4}/tox.ini +0 -0
@@ -9,6 +9,142 @@ source tree carries a version literal that could disagree with this file.
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
+ ## [0.3.4] - 2026-11-16
13
+
14
+ ### Added
15
+
16
+ - **The ternary liquidus figure draws the solidus with `get_plot('tx', solidus=True)`** (off by
17
+ default). Each triangle of three solid phases is drawn flat at the temperature the liquid leaves
18
+ it, outlined in the colour of a binary tie line. In a browser, the parts of an outline that lie
19
+ behind the liquidus from the camera are not drawn, and the triangle under the pointer is lightly
20
+ filled with the three phases' colours, each strongest at its own corner; a static export draws
21
+ every outline whole and no fill.
22
+ `TLIPlotter.solidus_triangles()` returns the triangles: the three phases, their
23
+ compositions, the liquid's composition and the temperature. They are read from the
24
+ three-field joints of the drawn liquidus; a triangle whose last liquid is too dilute in a
25
+ component for the surface to hold its joint (next to a low-melting element that does not mix
26
+ with the others) is solved from the solids' lower hull instead. The bottom of a phase's
27
+ `liquidus_ranges()` is lowered to its coldest solidus triangle whether or not the triangles
28
+ are drawn; with `solidus=True` the drawn temperature window reaches down to the coldest
29
+ triangle unless `temp_range` pins its floor.
30
+ - **`TLIPlotter.liquidus_ranges()`** returns each solid phase's lowest and highest temperature
31
+ in contact with the liquid, read from the phase fields of the last `'tx'` plot. The hull
32
+ table reports a phase's top on its `T_incr` ladder (25 K with `hull_mode='gtx'`); the field
33
+ gives it to the mesh, and exactly for a phase that melts congruently.
34
+ - **`TernaryLiquidInterpolation.edit_phases(edits)`** (`gliquid.imputation.edit_ternary_phases`)
35
+ applies a list of phase removals, temperature changes and additions in one call. A removal
36
+ leaves every DFT entry at the phase's composition off the hull.
37
+ - **`hold_hull=True`** on the ternary imputation calls places a phase that would push a stable
38
+ phase off the 0 K hull instead of refusing it: its enthalpy is held at the deepest value that
39
+ keeps those phases, and it carries the entropy at which it still leaves the hull at the
40
+ requested temperature. The record reports that entropy (`entropy`) and the phases the
41
+ unheld enthalpy would have displaced (`displaces`).
42
+ - **A ternary system's entries as a list, and a list read back.**
43
+ `TernaryLiquidInterpolation.export_entries()` lists the entries of the 0 K solid hull as
44
+ `ComputedEntry` dicts of plain JSON types, imputed and user-defined phases included, each
45
+ with its corrections folded into its energy and its entropy under
46
+ `data["entropy_j_per_mol_k"]`;
47
+ `PhaseDiagram([ComputedEntry.from_dict(d) for d in entries])` builds the same hull.
48
+ `entry_list_edits(entries)` compares such a list with the system and returns the `edit_phases`
49
+ edits that give it the list's phases: a phase whose formation enthalpy or entropy differs is
50
+ changed, a phase at a new composition is added, and a phase the list has no entry for is
51
+ removed. Formation enthalpies are taken against the list's own elemental references, and the
52
+ elements whose reference differs from the system's are reported (`reference_shifts`).
53
+ - **`edit_phases` removes a phase the store imputed**, with the entries it stands in for, and
54
+ takes `"force": True` on a single edit.
55
+ - **`enthalpy=` and `entropy=`** on the ternary imputation calls and in `edit_phases` place a
56
+ phase by its formation enthalpy (J/mol-atom) or its entropy (J/mol-atom/K). Given both, the
57
+ phase carries them as they are. Given one with a temperature, the other is solved so the
58
+ phase leaves the hull at that temperature; given one with a `solidus` and no temperature, so
59
+ it joins the hull there on heating. A phase above the 0 K hull needs a positive entropy, and
60
+ a given enthalpy that would push a stable phase off the 0 K hull is refused (`hold_hull` does
61
+ not move it) unless `force` is set. `impute_phase` takes its temperature as optional.
62
+ - **`solidus=`** on the ternary imputation calls and in `edit_phases` places a phase on the
63
+ hull between two temperatures: it joins the hull at the solidus on heating and leaves it at
64
+ its temperature. Its enthalpy and entropy are solved from the envelope at both, so it lies
65
+ above the 0 K hull and displaces nothing there. The solidus must be a temperature at which
66
+ the liquid reaches the phase's composition, and the solved entropy may take up to 0.9 of the
67
+ envelope's at the top (`SOLIDUS_ENTROPY_SHARE`); a refusal reports the nearest solidus that
68
+ works (`solidus_limit_k`).
69
+ - **An imputed entry carrying an entropy is placed above the 0 K hull**, as a user-defined
70
+ one already was, and a binary edge figure draws a hull entry with the entropy it carries
71
+ (it used zero).
72
+
73
+ ### Changed
74
+
75
+ - **Ternary phase fields with a two-liquid region are drawn faster in both hull modes: about
76
+ 1.5 times over a 2,300-system set, more than 4 times where they were slowest** (Bi-Sn-Th 458 s
77
+ to 96 s with `hull_mode='gtx'`, 642 s to 92 s with `'hsx'`). The binodal solver calls the
78
+ liquid model fewer times, on more points per call, and a triple point's Jacobian and its step
79
+ halvings each take one evaluation of the sheets; these steps leave the drawn surface as it
80
+ was. The lower hulls of one build share the hull of their composition points, which shortens
81
+ the hull stage by about a tenth. The search for a re-entrant two-liquid window drops a point
82
+ once its best value lies far from a window (`SEARCH.hump_reach`), which takes a further sixth
83
+ off the 14 slowest systems and leaves their surfaces bit-identical.
84
+ - **The edge of a two-liquid field is located to 2e-4 in mole fraction** (`WALL.width`), or
85
+ to 0.8% of the distance to the nearest side of the triangle where that is narrower,
86
+ instead of a millionth of each mesh edge, and a crossing with the two-liquid sheet is placed
87
+ once the two sheets agree to the 0.01 K that sheet is solved to. A wall's two vertices sit at
88
+ the two ends of that bracket. The liquidus at the grid nodes is unchanged; vertices next to a
89
+ two-liquid wall move by less than the bracket.
90
+ - **The binary edge figures of a ternary build are made about three times faster** (a median
91
+ of 1.6 s to 0.5 s per system over 30 systems), which shortens `process_data()` by a fifth
92
+ with `hull_mode='gtx'` and by over a quarter with `'hsx'`. `plot_tx` makes each phase line
93
+ and tie line as one trace instead of building a `plotly.express` figure for it; the figures
94
+ are unchanged.
95
+ - **A cliff at the edge of a two-liquid field is drawn without dark slivers or fins.** Every
96
+ face of the partition lists its vertices counter-clockwise, so neighbouring faces are shaded
97
+ alike; a wall's vertex on the two-liquid side sits `WALL.setback` (5e-4 in plot units) inside
98
+ the wall and takes the two-liquid sheet there; and an edge that leaves the field up a rise of
99
+ more than `WALL.jump` is split until the surface follows the sheet, its miss measured across
100
+ the surface as for the edges leaving a side. Vertices next to walls and steep edges move; the
101
+ fields and the liquidus at the grid nodes are unchanged.
102
+ - **The dotted outline of the two-liquid field is not drawn along the sides of the composition
103
+ triangle.** Stretches within `GAP_OUTLINE_CLEARANCE` (0.01 in mole fraction) of a side are
104
+ left out, and so is a run of the rest that never gets twice that far from the sides.
105
+ `field_boundaries(partition, phase, clear=...)` takes the clearance and returns the whole
106
+ outline without it.
107
+ - **A piece of the two-liquid field that leads the solids by at most 10 K (`SHALLOW_GAP`)
108
+ belongs to the solids' fields**: it has no outline, and each of its faces goes to the solid
109
+ hottest there. The surface keeps its temperatures.
110
+
111
+ ### Fixed
112
+
113
+ - **`adjust_phase_temperature` no longer refuses a move because of a phase that is only
114
+ stable while the adjusted phase is lifted out.** The 0 K hull guard protected every compound
115
+ stable once the phase's DFT entries were left off, including ones the phase normally hides
116
+ (Ag-Na: moving NaAg2 was refused for displacing NaAg3, which is not on the hull). It now
117
+ protects the compounds that are stable with those entries in place.
118
+ - **Three solid phase fields on the ternary liquidus now meet at their triple point.** Where
119
+ the triple point lay outside the mesh triangle whose three nodes carry the three phases, the
120
+ fields were joined at the nearest point of that triangle, and one triple point could be drawn
121
+ as several such joints. This happened next to a side or a corner of the diagram, where a
122
+ liquidus sheet is steep: on a 31-system sample, 23 systems had a joint whose three sheets
123
+ differed by more than 1 K and 7 by more than 25 K (251 K in Rb-Si-V). Such a triangle now has
124
+ an edge split, where the third phase is the hottest at the crossing of the edge's two phases,
125
+ until it holds the triple point; every joint of the sample is then within 0.005 K. Over a
126
+ 2,300-system set the surface gains 0.9% more vertices (17% at most) and the figure is drawn
127
+ 4% faster, because the refinement no longer samples new triangles that are too small to
128
+ split. The lowest and highest temperatures `TLIPlotter.liquidus_ranges` reports for a field
129
+ move with its joints.
130
+ - **Two solid phase fields now meet the two-liquid field where their own boundary enters
131
+ it.** Such a joint was left at the nearest point of the mesh triangle whose nodes carry the
132
+ three fields: on 100 systems with a two-liquid field, 203 of 447 joints away from the sides
133
+ had the two solids' sheets more than 0.05 K apart (44 K at most). The edges of these
134
+ triangles are now split as those of three solid phases are, and the joint is placed by
135
+ bisecting the solids' boundary on whether the two-liquid sheet is the hottest
136
+ (`GAP_JOINT`), which also places a joint on a two-liquid wall, where the three sheets are
137
+ never equal. One of the 450 joints is then more than 0.05 K apart (0.18 K). A joint the
138
+ bisection leaves with the two solids' sheets more than 1 K apart, as against a side of the
139
+ triangle, takes the point where the three sheets meet when the solids are closer there. A
140
+ joint at a corner of the triangle can still be open.
141
+ - `extract_digitized_liquidus` reads a narrow few-vertex `L` wedge (at most 0.05 wide in
142
+ composition) from its whole outline instead of keeping its hottest tip as the only point.
143
+ - `phase_transitions.json` cites the CRC Handbook instead of Wolfram ElementData for the
144
+ melting points of Ce, Nd, Tb, Ho and Yb (92nd ed.) and the enthalpies of fusion of Tb, Dy, Ho,
145
+ Lu and Pm (97th ed., "Physical Properties of the Rare Earth Metals"; Ho, Lu and Pm are
146
+ estimates). No value changes.
147
+
12
148
  ## [0.3.3] - 2026-11-09
13
149
 
14
150
  ### Added
@@ -962,7 +1098,8 @@ earlier published versions to diff against; this entry describes what the packag
962
1098
  - **An empty Materials Project fetch now raises rather than being cached.** A zero-entry result
963
1099
  used to be written out as a 2-byte `[]`, which every later read then accepted as a warm cache.
964
1100
 
965
- [Unreleased]: https://github.com/willwerj/gliquid_python/compare/v0.3.3...HEAD
1101
+ [Unreleased]: https://github.com/willwerj/gliquid_python/compare/v0.3.4...HEAD
1102
+ [0.3.4]: https://github.com/willwerj/gliquid_python/compare/v0.3.3...v0.3.4
966
1103
  [0.3.3]: https://github.com/willwerj/gliquid_python/compare/v0.3.2...v0.3.3
967
1104
  [0.3.2]: https://github.com/willwerj/gliquid_python/compare/v0.3.1...v0.3.2
968
1105
  [0.3.1]: https://github.com/willwerj/gliquid_python/compare/v0.3.0...v0.3.1
@@ -7,8 +7,8 @@ abstract: >-
7
7
  liquid descriptions.
8
8
  type: software
9
9
  # A literal: bump `version` and `date-released` by hand at each release (CONTRIBUTING.md).
10
- version: "0.3.3"
11
- date-released: "2026-11-09"
10
+ version: "0.3.4"
11
+ date-released: "2026-11-16"
12
12
  license: MIT
13
13
  repository-code: "https://github.com/willwerj/gliquid_python"
14
14
  url: "https://viz.whsunresearch.group/gliquid/interactive-matrix.html"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: gliquid
3
- Version: 0.3.3
3
+ Version: 0.3.4
4
4
  Summary: A package for fitting DFT-referenced liquid free energies from digitized equilibrium phase boundaries
5
5
  Project-URL: Homepage, https://viz.whsunresearch.group/gliquid/interactive-matrix.html
6
6
  Project-URL: TernaryInterpolation, https://viz.whsunresearch.group/gliquid/ternary-interpolation/
@@ -21,7 +21,7 @@
21
21
  "source": [
22
22
  "## UNCOMMENT THIS BLOCK FOR GOOGLE COLAB\n",
23
23
  "# !git clone --depth 1 https://github.com/willwerj/gliquid_python.git # per-system data in cache/\n",
24
- "# !pip install -q \"gliquid==0.3.3\" \"pymatgen<2026\" # keeps Colab's requests==2.32.4\n",
24
+ "# !pip install -q \"gliquid==0.3.4\" \"pymatgen<2026\" # keeps Colab's requests==2.32.4\n",
25
25
  "# import gliquid.config as cfg\n",
26
26
  "# cfg.set_cache_dir(\"/content/gliquid_python/cache\")\n",
27
27
  "# from google.colab import output\n",
@@ -21,7 +21,7 @@
21
21
  "source": [
22
22
  "## UNCOMMENT THIS BLOCK FOR GOOGLE COLAB\n",
23
23
  "# !git clone --depth 1 https://github.com/willwerj/gliquid_python.git # per-system data in cache/\n",
24
- "# !pip install -q \"gliquid==0.3.3\" \"pymatgen<2026\" # keeps Colab's requests==2.32.4\n",
24
+ "# !pip install -q \"gliquid==0.3.4\" \"pymatgen<2026\" # keeps Colab's requests==2.32.4\n",
25
25
  "# import gliquid.config as cfg\n",
26
26
  "# cfg.set_cache_dir(\"/content/gliquid_python/cache\")\n",
27
27
  "# from google.colab import output\n",
@@ -71,7 +71,7 @@
71
71
  "outputs": [],
72
72
  "source": [
73
73
  "!git clone --depth 1 https://github.com/willwerj/gliquid_python.git\n",
74
- "!pip install -q \"gliquid==0.3.3\" \"pymatgen<2026\"\n",
74
+ "!pip install -q \"gliquid==0.3.4\" \"pymatgen<2026\"\n",
75
75
  "from google.colab import output\n",
76
76
  "output.enable_custom_widget_manager()"
77
77
  ]
@@ -30,7 +30,7 @@
30
30
  "source": [
31
31
  "## UNCOMMENT THIS BLOCK FOR GOOGLE COLAB\n",
32
32
  "# !git clone --depth 1 https://github.com/willwerj/gliquid_python.git # per-system data in cache/\n",
33
- "# !pip install -q \"gliquid==0.3.3\" \"pymatgen<2026\" # keeps Colab's requests==2.32.4\n",
33
+ "# !pip install -q \"gliquid==0.3.4\" \"pymatgen<2026\" # keeps Colab's requests==2.32.4\n",
34
34
  "# import gliquid.config as cfg\n",
35
35
  "# cfg.set_cache_dir(\"/content/gliquid_python/cache\")\n",
36
36
  "# from google.colab import output\n",
@@ -22,7 +22,7 @@
22
22
  "source": [
23
23
  "## UNCOMMENT THIS BLOCK FOR GOOGLE COLAB\n",
24
24
  "# !git clone --depth 1 https://github.com/willwerj/gliquid_python.git # per-system data in cache/\n",
25
- "# !pip install -q \"gliquid==0.3.3\" \"pymatgen<2026\" # keeps Colab's requests==2.32.4\n",
25
+ "# !pip install -q \"gliquid==0.3.4\" \"pymatgen<2026\" # keeps Colab's requests==2.32.4\n",
26
26
  "# import gliquid.config as cfg\n",
27
27
  "# cfg.set_cache_dir(\"/content/gliquid_python/cache\")\n",
28
28
  "# from google.colab import output\n",
@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
18
18
  commit_id: str | None
19
19
  __commit_id__: str | None
20
20
 
21
- __version__ = version = '0.3.3'
22
- __version_tuple__ = version_tuple = (0, 3, 3)
21
+ __version__ = version = '0.3.4'
22
+ __version_tuple__ = version_tuple = (0, 3, 4)
23
23
 
24
24
  __commit_id__ = commit_id = None
@@ -32,6 +32,7 @@ import gliquid.plotting.export as plot_export
32
32
  import gliquid.solid_coverage as solid_coverage
33
33
  import gliquid.solution as solution
34
34
  from gliquid.cache import (
35
+ ENTROPY_KEY,
35
36
  imputed_entry_label,
36
37
  non_dft_entry_kind,
37
38
  non_dft_entry_label,
@@ -489,10 +490,18 @@ def build_phases_from_chull(
489
490
 
490
491
  Returns:
491
492
  list[Phase]: Elemental polymorphs and line compounds sorted by composition,
492
- with the 'L' liquid sentinel appended last.
493
+ with the 'L' liquid sentinel appended last. A line compound is a stable entry of
494
+ ``ch``, or an entry carrying an entropy (``data[ENTROPY_KEY]``, J/mol-atom/K), which is
495
+ placed even above the hull.
493
496
  """
494
497
  phases = _endpoint_polymorphs(components, component_data, exclude_spacegroups)
495
- for entry in ch.stable_entries:
498
+ stable = list(ch.stable_entries)
499
+ lifted = [
500
+ e
501
+ for e in ch.all_entries
502
+ if e not in stable and (getattr(e, "data", None) or {}).get(ENTROPY_KEY)
503
+ ]
504
+ for entry in stable + lifted:
496
505
  composition = api.entry_frac_along(ch, entry, components)[0]
497
506
  if composition in [
498
507
  p.fraction_in(components)[0] for p in phases
@@ -504,7 +513,7 @@ def build_phases_from_chull(
504
513
  phase_type="solid",
505
514
  composition=api.entry_original(entry).composition,
506
515
  enthalpy=EV_ATOM_TO_J_MOL * ch.get_form_energy_per_atom(entry),
507
- entropy=0,
516
+ entropy=float((getattr(entry, "data", None) or {}).get(ENTROPY_KEY, 0.0)),
508
517
  **hull_phase_fields(entry),
509
518
  ),
510
519
  )
@@ -9,6 +9,7 @@ ORCID: https://orcid.org/0000-0001-5205-0075
9
9
  from __future__ import annotations
10
10
 
11
11
  from collections import defaultdict
12
+ from functools import lru_cache
12
13
 
13
14
  import numpy as np
14
15
  import pandas as pd
@@ -38,15 +39,21 @@ def _hull_from_fictitious(real_points, fict_points, second_filter=None):
38
39
  return real_simplices
39
40
 
40
41
 
42
+ @lru_cache(maxsize=8)
43
+ def _base_hull(coordinates: bytes, columns: int) -> np.ndarray:
44
+ """The convex-hull vertices of the points whose float64 bytes are ``coordinates``
45
+ (``columns`` per point), followed by their mean. Shared between calls: do not modify."""
46
+ points = np.frombuffer(coordinates).reshape(-1, columns)
47
+ vertices = points[ConvexHull(points).vertices]
48
+ return np.vstack((vertices, np.mean(vertices, axis=0)))
49
+
50
+
41
51
  def lower_convex_hull(points, vertical_simplices=False):
42
52
  # Lower convex hull of an N-dimensional Xi-E space (energy-like axis last) by the
43
53
  # sub-hull-centroid fictitious-point strategy; returns the lower-hull simplices.
44
54
 
45
- sub_points = points[:, :-1]
46
- sub_hull = ConvexHull(sub_points)
47
- sub_hull_points = sub_points[sub_hull.vertices]
48
- center = np.mean(sub_hull_points, axis=0)
49
- sub_hull_points = np.vstack((sub_hull_points, center))
55
+ sub_points = np.ascontiguousarray(points[:, :-1], dtype=float)
56
+ sub_hull_points = _base_hull(sub_points.tobytes(), sub_points.shape[1])
50
57
 
51
58
  # Compute upper bound for fictitious points using single-pass ptp
52
59
  h_data = points[:, -1]
@@ -20,6 +20,7 @@ _EXPORTS: dict[str, str] = {
20
20
  "list_binary_imputation_targets": "gliquid.imputation.binary_imputation",
21
21
  "impute_ternary_phase": "gliquid.imputation.ternary_imputation",
22
22
  "adjust_ternary_phase_temperature": "gliquid.imputation.ternary_imputation",
23
+ "edit_ternary_phases": "gliquid.imputation.ternary_imputation",
23
24
  "IMPUTED_ID_PREFIX": "gliquid.cache",
24
25
  "PROVENANCE_KEY": "gliquid.imputation.core",
25
26
  "REPLACES_KEY": "gliquid.imputation.core",
@@ -0,0 +1,245 @@
1
+ """A ternary system's solid entries as a list, and the phase edits that bring a system to one.
2
+
3
+ :func:`export_entries` lists the entries of a ternary object's 0 K solid hull as
4
+ ``ComputedEntry`` dicts, imputed and user-defined phases included, each with its entropy under
5
+ ``data[gliquid.cache.ENTROPY_KEY]``. The list is what ``pymatgen`` reads::
6
+
7
+ PhaseDiagram([ComputedEntry.from_dict(d) for d in entries])
8
+
9
+ :func:`entry_list_edits` compares such a list with a ternary object and returns the edits
10
+ (:func:`gliquid.imputation.ternary_imputation.edit_ternary_phases`) that give the object the
11
+ list's phases.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import dataclasses
17
+ import json
18
+
19
+ from monty.json import MontyEncoder
20
+ from pymatgen.entries.computed_entries import ComputedEntry
21
+
22
+ import gliquid.api as api
23
+ import gliquid.cache as cache
24
+ from gliquid.imputation.core import phase_diagram_enthalpy_at
25
+ from gliquid.phase import EV_ATOM_TO_J_MOL
26
+
27
+ #: Most, eV/atom, two reference energies of one element may differ and count as the same.
28
+ REFERENCE_TOL_EV = 1e-6
29
+ #: Most, J/mol-atom and J/mol-atom/K, a listed phase may differ from the object's and count as
30
+ #: unchanged.
31
+ ENTHALPY_TOL_J = 0.5
32
+ ENTROPY_TOL = 1e-6
33
+ #: Decimal places compositions are compared to.
34
+ COMPOSITION_DECIMALS = 6
35
+ #: The module a listed entry names as its class's.
36
+ ENTRY_MODULE = "pymatgen.entries.computed_entries"
37
+
38
+
39
+ def _entropy(entry) -> float:
40
+ return float((getattr(entry, "data", None) or {}).get(cache.ENTROPY_KEY, 0.0))
41
+
42
+
43
+ def export_entries(tli) -> list[dict]:
44
+ """The entries of ``tli``'s 0 K solid hull (:meth:`TernaryLiquidInterpolation.solid_hull`)
45
+ as ``ComputedEntry`` payloads of plain JSON types.
46
+
47
+ Every entry carries its total energy with its corrections in it (``correction`` 0 and no
48
+ ``energy_adjustments``), and its entropy, J/mol-atom/K, under
49
+ ``data[gliquid.cache.ENTROPY_KEY]`` (0 for an entry without one). Entries an imputed or
50
+ user-defined phase stands in for, and excluded ones, are not listed.
51
+ """
52
+ out = []
53
+ for entry in tli.solid_hull().all_entries:
54
+ original = api.entry_original(entry)
55
+ payload = {
56
+ "@module": ENTRY_MODULE,
57
+ "@class": "ComputedEntry",
58
+ "composition": original.composition.as_dict(),
59
+ "energy": float(original.energy),
60
+ "correction": 0.0,
61
+ "energy_adjustments": [],
62
+ "entry_id": original.entry_id,
63
+ "parameters": getattr(original, "parameters", None) or {},
64
+ "data": {
65
+ **(getattr(original, "data", None) or {}),
66
+ cache.ENTROPY_KEY: _entropy(original),
67
+ },
68
+ }
69
+ out.append(json.loads(json.dumps(payload, cls=MontyEncoder)))
70
+ return out
71
+
72
+
73
+ @dataclasses.dataclass
74
+ class EntryListEdits:
75
+ """What a list of entries changes on a ternary object.
76
+
77
+ Attributes:
78
+ edits: the edits, as :func:`gliquid.imputation.ternary_imputation.edit_ternary_phases`
79
+ takes them, that give the object the list's phases: a ``{"remove": phase}`` per
80
+ name of ``removed``, then a ``{"phase": phase, "enthalpy", "entropy", "force":
81
+ True}`` or ``{"composition", "name", "enthalpy", "entropy", "force": True}`` per
82
+ name of ``changed`` and of ``added``.
83
+ changed: the object's phases the list gives another formation enthalpy or entropy.
84
+ added: the phases the list holds at compositions where the object has none.
85
+ removed: the object's phases at compositions where the list has no entry.
86
+ unchanged: how many of the object's phases the list leaves as they are.
87
+ ignored: ids of the listed entries that are not the object's own and change nothing:
88
+ those with an element outside the system, and those above the object's 0 K hull,
89
+ without an entropy, at a composition where the object has no phase.
90
+ reference_shifts: element -> the list's reference energy minus the object's, eV/atom,
91
+ for the elements where they differ by more than :data:`REFERENCE_TOL_EV`.
92
+ """
93
+
94
+ edits: list[dict] = dataclasses.field(default_factory=list)
95
+ changed: list[str] = dataclasses.field(default_factory=list)
96
+ added: list[str] = dataclasses.field(default_factory=list)
97
+ removed: list[str] = dataclasses.field(default_factory=list)
98
+ unchanged: int = 0
99
+ ignored: list[str] = dataclasses.field(default_factory=list)
100
+ reference_shifts: dict[str, float] = dataclasses.field(default_factory=dict)
101
+
102
+
103
+ def _phases(tli, hull) -> dict[tuple, dict]:
104
+ """The compound phases of ``tli`` by composition: the stable entry of ``hull`` there, or
105
+ the entry of lowest energy that carries an entropy."""
106
+ components = list(tli.components)
107
+
108
+ def described(entry, stable):
109
+ fractions = {c: float(entry.composition.get_atomic_fraction(c)) for c in components}
110
+ return {
111
+ "name": api.hull_entry_name(entry),
112
+ "fractions": fractions,
113
+ "enthalpy": float(hull.get_form_energy_per_atom(entry)) * EV_ATOM_TO_J_MOL,
114
+ "entropy": _entropy(entry),
115
+ "stable": stable,
116
+ }
117
+
118
+ stable_ids = {id(entry) for entry in hull.stable_entries}
119
+ found: dict[tuple, dict] = {}
120
+ for entry in sorted(hull.all_entries, key=lambda e: e.energy_per_atom):
121
+ stable = id(entry) in stable_ids
122
+ if len(entry.composition.elements) < 2 or not (stable or _entropy(entry) > 0.0):
123
+ continue
124
+ phase = described(entry, stable)
125
+ key = _key(phase["fractions"], components)
126
+ if key not in found or (stable and not found[key]["stable"]):
127
+ found[key] = phase
128
+ return found
129
+
130
+
131
+ def _key(fractions, components) -> tuple:
132
+ return tuple(round(fractions[c], COMPOSITION_DECIMALS) for c in components)
133
+
134
+
135
+ def _label(entry) -> str:
136
+ data = getattr(entry, "data", None) or {}
137
+ if data.get("label"):
138
+ return str(data["label"])
139
+ if cache.non_dft_entry_kind(entry) is not None:
140
+ return cache.non_dft_entry_label(entry)
141
+ return entry.composition.reduced_formula
142
+
143
+
144
+ def entry_list_edits(tli, entry_dicts) -> EntryListEdits:
145
+ """The edits that give ``tli`` the phases of a list of entries.
146
+
147
+ The list's phase at a composition is its entry of lowest energy there. Formation enthalpies
148
+ are taken against the list's own reference energies (its elemental entry of lowest energy
149
+ per atom; ``tli``'s for an element the list has none of), so a list on other references
150
+ keeps its formation enthalpies. ``tli`` is not changed.
151
+
152
+ Args:
153
+ tli: a :class:`~gliquid.ternary.TernaryLiquidInterpolation`.
154
+ entry_dicts: ``ComputedEntry.as_dict()`` payloads, as :func:`export_entries` lists them.
155
+
156
+ Returns:
157
+ EntryListEdits: the edits and what they change.
158
+
159
+ Raises:
160
+ ValueError: an item of ``entry_dicts`` is not a ``ComputedEntry`` payload.
161
+ """
162
+ components = list(tli.components)
163
+ hull = tli.solid_hull()
164
+ out = EntryListEdits()
165
+
166
+ listed = []
167
+ for n, payload in enumerate(entry_dicts):
168
+ try:
169
+ entry = ComputedEntry.from_dict(payload)
170
+ except Exception as error:
171
+ raise ValueError(f"item {n} of the list is not a ComputedEntry: {error}") from error
172
+ if {str(el) for el in entry.composition.elements} <= set(components):
173
+ listed.append(entry)
174
+ else:
175
+ out.ignored.append(str(entry.entry_id))
176
+
177
+ own = {str(el): float(entry.energy_per_atom) for el, entry in hull.el_refs.items()}
178
+ refs = dict(own)
179
+ for symbol in components:
180
+ energies = [
181
+ float(e.energy_per_atom)
182
+ for e in listed
183
+ if [str(el) for el in e.composition.elements] == [symbol]
184
+ ]
185
+ if energies:
186
+ refs[symbol] = min(energies)
187
+ out.reference_shifts = {
188
+ symbol: refs[symbol] - own[symbol]
189
+ for symbol in components
190
+ if abs(refs[symbol] - own[symbol]) > REFERENCE_TOL_EV
191
+ }
192
+
193
+ wanted: dict[tuple, dict] = {}
194
+ for entry in sorted(listed, key=lambda e: e.energy_per_atom):
195
+ if len(entry.composition.elements) < 2:
196
+ continue
197
+ fractions = {c: float(entry.composition.get_atomic_fraction(c)) for c in components}
198
+ base = sum(fractions[c] * refs[c] for c in components)
199
+ wanted.setdefault(
200
+ _key(fractions, components),
201
+ {
202
+ "entry": entry,
203
+ "fractions": fractions,
204
+ "enthalpy": (float(entry.energy_per_atom) - base) * EV_ATOM_TO_J_MOL,
205
+ "entropy": _entropy(entry),
206
+ },
207
+ )
208
+
209
+ phases = _phases(tli, hull)
210
+ taken = {phase["name"] for phase in phases.values()}
211
+ held = {cache.canonical_entry_id(entry.entry_id) for entry in hull.all_entries}
212
+ for key, phase in phases.items():
213
+ if key not in wanted:
214
+ out.removed.append(phase["name"])
215
+ out.edits.append({"remove": phase["name"]})
216
+ for key, want in wanted.items():
217
+ given = {"enthalpy": want["enthalpy"], "entropy": want["entropy"], "force": True}
218
+ phase = phases.get(key)
219
+ if phase is None:
220
+ above = want["enthalpy"] >= phase_diagram_enthalpy_at(hull, want["fractions"])
221
+ if above and not want["entropy"] > 0.0:
222
+ if cache.canonical_entry_id(want["entry"].entry_id) not in held:
223
+ out.ignored.append(str(want["entry"].entry_id))
224
+ continue
225
+ name, n = _label(want["entry"]), 1
226
+ while name in taken:
227
+ n += 1
228
+ name = f"{_label(want['entry'])}-{n}"
229
+ taken.add(name)
230
+ out.added.append(name)
231
+ out.edits.append({"composition": want["fractions"], "name": name, **given})
232
+ elif (
233
+ abs(want["enthalpy"] - phase["enthalpy"]) <= ENTHALPY_TOL_J
234
+ and abs(want["entropy"] - phase["entropy"]) <= ENTROPY_TOL
235
+ ):
236
+ out.unchanged += 1
237
+ else:
238
+ out.changed.append(phase["name"])
239
+ target = (
240
+ {"phase": phase["name"]}
241
+ if phase["stable"]
242
+ else {"composition": phase["fractions"], "name": phase["name"]}
243
+ )
244
+ out.edits.append({**target, **given})
245
+ return out