{"id":16554463,"url":"https://github.com/tkphd/kks-binary-solidification","last_synced_at":"2025-07-05T02:05:23.007Z","repository":{"id":148157562,"uuid":"59316682","full_name":"tkphd/KKS-binary-solidification","owner":"tkphd","description":"Phase field model for binary solidification using Kim-Kim-Suzuki interface description","archived":false,"fork":false,"pushed_at":"2021-04-09T20:24:28.000Z","size":7245,"stargazers_count":32,"open_issues_count":2,"forks_count":9,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-27T18:57:09.009Z","etag":null,"topics":["fipy","kim-kim-suzuki","kks","materials-science","mmsp","phase-field","solidification"],"latest_commit_sha":null,"homepage":"https://nbviewer.jupyter.org/github/tkphd/KKS-binary-solidification/blob/main/FiPy-KKS.ipynb","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tkphd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-20T18:19:50.000Z","updated_at":"2025-05-07T08:36:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"f3f0c3d2-6943-48bf-9f41-0d37e36e1307","html_url":"https://github.com/tkphd/KKS-binary-solidification","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tkphd/KKS-binary-solidification","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkphd%2FKKS-binary-solidification","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkphd%2FKKS-binary-solidification/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkphd%2FKKS-binary-solidification/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkphd%2FKKS-binary-solidification/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tkphd","download_url":"https://codeload.github.com/tkphd/KKS-binary-solidification/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkphd%2FKKS-binary-solidification/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263646636,"owners_count":23494007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fipy","kim-kim-suzuki","kks","materials-science","mmsp","phase-field","solidification"],"created_at":"2024-10-11T19:51:31.898Z","updated_at":"2025-07-05T02:05:23.000Z","avatar_url":"https://github.com/tkphd.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KKS Binary Solidification with FiPy\n\nThis notebook contains code for binary solidification using the Kim-Kim-Suzuki model [1]\nfor interfacial energy. This allows easy specification of gamma, but requires constant\nchemical potential through the interface. The implementation involves iteratively solving\nfor chemical composition in pure phases such that the chemical potential constraint is\nsatisfied [2].\n\nQuestions/comments to trevor.keller@nist.gov (Trevor Keller). Cite with the following DOI:\n\n[![DOI](https://zenodo.org/badge/59316682.svg)](https://zenodo.org/badge/latestdoi/59316682)\n\nReferences:\n1. Kim, Kim, and Suzuki. \"Phase-field model for binary alloys.\"\n    _Physical Review E_ 60:6;7186-7197 (1999). \n2. Provatas and Elder. _Phase-Field Methods in Materials Science and Engineering_,\n    Chapter 6, Section 9. Wiley VCH: Weinheim, Germany. 2010.\n\n## Model Description (paraphrased after Provatas \u0026 Elder)\n\nWe are setting out to simulate solidification of two-component alloy with a lenticular\nphase diagram, or \"binary isomorphous\" system, such as Cu-Ni. The free energy curves for\npure phases, $f_S$ and $f_L$, are generated from a CALPHAD database, rather than a regular\nsolution model.\n\nIn addition to this thermodynamic description, we are adopting the KKS treatment of\ndiffuse interfaces. This simply means that at equilibrium, chemical potential is constant\nthrough the interface, and composition varies to make it so. More concretely, composition\nis defined by the phase fraction $\\phi$ and two fictitious concentration fields, $C_S$ and\n$C_L$, representing composition of the pure phase, as\n\n$$c = h(\\phi)C_S + (1-h(\\phi))C_L,$$\n\nwhere the interpolation function $h(\\phi)=\\phi^3(6\\phi^2-15\\phi+10)$ takes the values in\nsolid $h(\\phi=1)=1$ and liquid $h(\\phi=0)=0$. At equilibrium,\n\n$$\\mu = \\left.\\frac{\\partial f_S}{\\partial c}\\right|_{c=C_S} = \\left.\\frac{\\partial\nf_L}{\\partial c}\\right|_{c=C_L}.$$\n\nTaken together, and introducing a double-well function $g(\\phi)=\\phi^2(1-\\phi)^2$, the\nthermodynamic and interfacial treatments provide the bulk free energy,\n\n$$f(\\phi,c,T) = \\omega g(\\phi) + h(\\phi)f_S(C_S,T) + (1-h(\\phi))f_L(C_L,T).$$\n\nNow, assuming nonconserved (Allen-Cahn) dynamics for $\\phi$ and conserved (Cahn-Hilliard)\ndynamics for $c$, we can write the equations of motion\n\n$$\\frac{\\partial\\phi}{\\partial t} = -M_\\phi\\frac{\\delta\\mathcal{F}}{\\delta\\phi}\n\\rightarrow \\tau\\frac{\\partial\\phi}{\\partial t} = \\epsilon_\\phi^2\\nabla^2\\phi -\\omega\ng'(\\phi) + h'(\\phi)\\left[f_L(C_L) - f_S(C_S) - \\frac{\\partial f_L(C_L)}{\\partial c}(C_L -\nC_S)\\right]$$\n\n$$\\frac{\\partial c}{\\partial t} = \\nabla\\cdot M_c\\nabla\\frac{\\delta\\mathcal{F}}{\\delta c}\n= M_c\\nabla\\cdot Q(\\phi)\\left[h(\\phi)\\nabla C_S + (1-h(\\phi))\\nabla C_L\\right]$$\n\nwith phase-dependent mobility $Q(\\phi)=\\frac{1-\\phi}{(1+k) - (1-k)\\phi}$, partition\ncoefficient $k=\\frac{C_S^e}{C_L^e}$, and time constant $\\tau = M_\\phi^{-1}$.\n\n### The Wrinkle\n\n$C_S$ and $C_L$ are not constants, they are field variables whose values depend on $\\phi$\nand $c$. Determining their values requires solving for the common tangent, or the coupled\nroots\n\n$$f_1(C_S,C_L) = h(\\phi)C_S + (1-h(\\phi))C_L -c = 0$$\n\n$$f_2(C_S,C_L) = \\frac{\\partial f_S(C_S)}{\\partial c} - \\frac{\\partial f_L(C_L)}{\\partial c} = 0.$$\n\nWhile these equations can be solved using Newton's Method (cf. Provatas \u0026 Elder Appendix\nC.3), it's better to invoke a library, which we'll do a little later on. Even with a\nhighly optimized root solver, determining $(C_S,C_L)$ at every grid point gets\nprohibitively expensive. The standard approach is to construct a lookup table for $C_S$\nand $C_L$ covering $\\phi=[-\\delta,1+\\delta]$ and $c=[-\\delta,1+\\delta]$ with a reasonably\nhigh number of points, then interpolating from the LUT at runtime. For best results, use\nthe interpolated values as initial guesses for a touch-up iteration or two.\n\n## Running Locally\n\nIt is strongly recommended that you download this software using\n[git](https://git-scm.com/), the distributed version control software:\n\n``` bash\n$ git clone https://github.com/tkphd/KKS-binary-solidification.git\n```\n\n### Python\n\nThe Python version of this software depends on [FiPy](https://www.ctcms.nist.gov/fipy/)\nand [pycalphad](https://pycalphad.org/docs/latest/). It is probably best to install these\nin a [conda](https://docs.conda.io/en/latest/miniconda.html) environment. Please follow\nthe directions provided by those packages to configure your system. On Linux, installation\nwill look something like the following:\n\n```bash\n$ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh\n$ chmod +x Miniconda3-latest-Linux-x86_64.sh \n$ ./Miniconda3-latest-Linux-x86_64.sh\n# Complete the installation process\n$ conda create -n kks -c conda-forge python=3 fipy notebook numpy pycalphad scipy\n$ conda activate kks\n$ cd KKS-binary-solidification\n$ jupyter notebook\n```\n\nThis should open a web browser in the folder you cloned this repository into. Click on the\nfile named \"FiPy-KKS.ipynb\" and tinker to your heart's content.\n\n### C++\n\nThe C++ version of this code depends on [MMSP](https://github.com/mesoscale/mmsp) and\n[GSL](https://www.gnu.org/software/gsl/). MMSP is a header-only library, so you need only\ndownload it and set an environmental variable. In Linux, this is simple:\n\n``` bash\n$ git clone https://github.com/mesoscale/mmsp.git\n$ echo \"export MMSP_PATH=${PWD}/mmsp\" \u003e\u003e ~/.bashrc\n$ . ~/.bashrc\n```\n\nPlease follow the MMSP documentation if you wish to build utilities for\nconversion of output between various file formats.\n\nIf you do not already have them installed, you will need to install\n[Make](https://www.gnu.org/software/make/), and headers for\n[libpng](http://www.libpng.org/pub/png/libpng.html) and [zlib](https://www.zlib.net/).\nWith these dependencies satisfied, you should be able to build and run the program:\n\n``` bash\n$ cd ~/KKS-binary-solidification\n$ make\n$ ./KKS --help\n...\n$ ./KKS --example 2 start.dat\nSystem has 13.22% solid, 86.78% liquid, and composition 46.77% B. Equilibrium is 50.00% solid, 50.00% liquid.\n\nEquilibrium Cs=0.54, Cl=0.39. Timestep dt=9.00e-04\n```\n\nAt this point, the lookup table for *Cs* and *Cl* has been written to `consistentC.lut`,\nand visualizations of the various fields were exported as PNG images. Details are in the\n`generate` function in `KKS.cpp`. To evolve the system, run\n\n``` bash\n$ ./KKS start.dat 10000 1000\n```\n\nor similar; use `./KKS --help` again for details. If you built the utilities, you can\nconvert all the checkpoint files to PNG images using\n\n``` bash\n$ for f in *.dat; do mmsp2png $f; done\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkphd%2Fkks-binary-solidification","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftkphd%2Fkks-binary-solidification","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkphd%2Fkks-binary-solidification/lists"}