Class: Phase Field Crystal
Phase Field Crystal model.
- class comfit.phase_field_crystal.phase_field_crystal.PhaseFieldCrystal(dim, **kwargs)
Bases:
BaseSystem- __init__(dim, **kwargs)
Initializes a system to simulate a Phase Field Crystal.
This class is the base of the other phase field crystal models implemented in comfit.
Parameters
- dimint
The dimension of the system.
- **kwargsdict
Keyword arguments to set additional parameters. See https://comfitlib.com/ClassPhaseFieldCrystal/
Returns
- PhaseFieldCrystal
The system object representing the phase field crystal simulation.
- calc_PFC_free_energy_density_and_chemical_potential(field=None, field_f=None)
Calculates the free energy density and chemical potential of the PFC.
Parameters
- fieldndarray, optional
The field to calculate the free energy density and chemical potential of. If None, self.psi is used.
- field_fndarray, optional
The Fourier transform of the field. If None, self.psi_f is used.
Returns
- tuple
A tuple containing: - free_energy_density (ndarray): The free energy density of the PFC - chemical_potential (ndarray): The chemical potential of the PFC
- calc_PFC_from_amplitudes(eta=None, rotation=None)
Calculate the PFC from the amplitudes.
Parameters
- etaarray_like, optional
The amplitudes to calculate the PFC from. If None, uses default amplitudes.
- rotationarray_like or float, optional
The rotation to apply to the crystal. If float, rotation around z-axis. If array, rotation vector [rx, ry, rz].
Returns
- ndarray
The phase field crystal density field.
- calc_amplitudes_with_dislocation(eta=None, x=None, y=None, dislocation_type=1)
Calculate the amplitudes with a single point dislocation inserted.
Parameters
- etaarray_like, optional
The amplitudes to insert the dislocation in. If None, uses default amplitudes.
- xfloat, optional
The x-coordinate of the dislocation. If None, uses system midpoint.
- yfloat, optional
The y-coordinate of the dislocation. If None, uses system midpoint.
- dislocation_typeint, optional
The dislocation type to insert, default is 1.
Returns
- ndarray
The amplitudes containing the dislocation.
Raises
- Exception
If the dimension of the system is not 2.
- calc_amplitudes_with_dislocation_dipole(eta=None, x1=None, y1=None, x2=None, y2=None, dislocation_type=1)
Insert a dislocation dipole in the system corresponding to dislocation type and its negative.
Parameters
- etaarray_like, optional
The amplitudes to insert the dislocation dipole in. If None, uses default amplitudes.
- x1float, optional
The x-coordinate of the first dislocation. If None, uses 1/3 of system width.
- y1float, optional
The y-coordinate of the first dislocation. If None, uses 1/2 of system height.
- x2float, optional
The x-coordinate of the second dislocation. If None, uses 2/3 of system width.
- y2float, optional
The y-coordinate of the second dislocation. If None, uses 1/2 of system height.
- dislocation_typeint, optional
The dislocation type to insert, default is 1.
Returns
- ndarray
The amplitudes with the dislocation dipole inserted.
Raises
- Exception
If the dimension of the system is not 2.
- calc_amplitudes_with_dislocation_ring(eta=None, position=None, radius=None, normal_vector=[0, 0, 1], dislocation_type=1)
Insert a dislocation ring in the system corresponding to dislocation type.
Parameters
- etaarray_like, optional
The amplitudes to insert the dislocation ring in. If None, uses default amplitudes.
- positionarray_like, optional
The position of the dislocation ring. If None, uses system midpoint.
- radiusfloat, optional
The radius of the dislocation ring. If None, uses 1/3 of minimum system dimension.
- normal_vectorarray_like, optional
The normal vector of the dislocation ring, default is [0, 0, 1].
- dislocation_typeint, optional
The dislocation type to insert, default is 1.
Returns
- ndarray
The amplitudes with the dislocation ring inserted.
Raises
- Exception
If the dimension of the system is not 3.
- calc_demodulate_PFC(only_primary_modes=True)
Demodulate the PFC to extract amplitudes.
Parameters
- only_primary_modesbool, optional
Whether to only extract primary reciprocal lattice modes, default is True.
Returns
- ndarray
The amplitudes corresponding to the demodulated PFC.
- calc_dislocation_density(eta=None)
Calculates the dislocation density.
Parameters
- etandarray, optional
The amplitudes to calculate the dislocation density from. If None, amplitudes are calculated using demodulation.
Returns
- ndarray
The dislocation density.
- calc_dislocation_nodes()
Calculates the dislocation nodes.
Parameters
None
Returns
- list
A list of dictionaries containing information about each dislocation node.
Raises
- Exception
If the PFC is distorted.
- calc_displacement_field_to_equilibrium()
Calculates the displacement field needed to put the PFC in mechanical equilibrium.
Parameters
None
Returns
- ndarray
The displacement field u that would bring the system to mechanical equilibrium
- calc_free_energy()
Calculate the total free energy of the system by integrating the free energy density over the computational domain.
This method computes the phase field crystal free energy density using calc_PFC_free_energy_density_and_chemical_potential, and then integrates it over the entire domain using calc_integrate_field.
Returns
- float
The total free energy of the system.
See Also
calc_PFC_free_energy_density_and_chemical_potential : Method that calculates the free energy density and chemical potential. calc_integrate_field : Method that integrates a field over the computational domain.
- calc_nonlinear_evolution_function_conserved_f(psi, t)
Calculate the nonlinear part of the evolution function for conserved dynamics.
Parameters
- psindarray
The phase field.
- tfloat
The time.
Returns
- ndarray
The nonlinear part of the evolution function in Fourier space.
- calc_nonlinear_evolution_function_unconserved_f(psi, t)
Calculate the nonlinear part of the evolution function for unconserved dynamics.
Parameters
- psindarray
The phase field.
- tfloat
The time.
Returns
- ndarray
The nonlinear part of the evolution function in Fourier space.
- calc_nonlinear_hydrodynamic_evolution_function_f(field, t)
Calculates the hydrodynamic evolution function of the PFC.
Parameters
- fieldndarray
The field to calculate the evolution function of.
- tfloat
The time.
Returns
- ndarray
The nonlinear evolution function for the hydrodynamic PFC in Fourier space.
- calc_omega_hydrodynamic_f()
Calculates the hydrodynamic evolution function omega_f.
Parameters
None
Returns
- ndarray
The hydrodynamic evolution function omega_f in Fourier space.
- calc_orientation_field()
Calculates the orientation field of the phase-field crystal.
- Args:
None
- Returns:
An orientation field, which is a vector field specifying the orientation of the crystal.
- calc_strain_tensor()
Calculates the strain of the phase-field crystal.
Parameters
None
Returns
- ndarray
The strain tensor.
- calc_strained_amplitudes()
Strains the PFC to equilibrium and returns the amplitudes.
Parameters
None
Returns
- tuple
Depending on the PFC type, returns either: - (final_strain, psi0, A, el_lambda, el_mu, el_gamma) for 1 independent amplitude - (final_strain, psi0, A, B, el_lambda, el_mu, el_gamma) for 2 independent amplitudes - (final_strain, psi0, A, B, C, el_lambda, el_mu, el_gamma) for 3 independent amplitudes
- calc_stress_divergence_f(field_f=None)
Calculates the divergence of the stress tensor in Fourier space.
Parameters
- field_fndarray, optional
The field in Fourier space. If None, uses the current system field.
Returns
- ndarray
The divergence of the stress tensor in Fourier space.
- calc_stress_tensor()
Calculates the stress of the phase-field crystal.
Parameters
None
Returns
- ndarray
The stress tensor.
- calc_stress_tensor_microscopic()
Calculate the microscopic stress of the phase-field crystal.
Parameters
None
Returns
- ndarray
The microscopic stress tensor of the phase-field crystal. For 2D: tensor with components [σxx, σxy, σyy]. For 3D: tensor with components [σxx, σxy, σxz, σyy, σyz, σzz].
Raises
- Exception
If the dimension of the system is 1D.
- calc_structure_tensor()
Calculates the structure tensor of the phase-field crystal.
Parameters
None
Returns
- ndarray
The structure tensor.
- calc_structure_tensor_f()
Calculates the structure tensor of the phase-field crystal in Fourier space.
Parameters
None
Returns
- ndarray
The structure tensor in Fourier space.
- conf_PFC_from_amplitudes(eta=None, rotation=None)
Configures the PFC from the amplitudes.
Parameters
- etaarray_like, optional
The amplitudes to configure the PFC from.
- rotationarray_like, optional
Rotation vector to apply to the crystal.
Returns
- None
Configures self.psi and self.psi_f.
- conf_advect_PFC(u)
Advects the PFC according to the displacement field u.
Parameters
- uarray_like
The displacement field to advect the PFC with.
Returns
- None
Updates the PFC state.
- conf_apply_distortion(distortion, update_q_and_a_vectors=False)
Applies a distortion to the PFC.
Parameters
- distortionfloat or array_like
The distortion to apply to the PFC. Can be a float for uniform distortion or a matrix for more complex distortions.
- update_q_and_a_vectorsbool, optional
Whether to update the q-vectors and a-vectors, by default False
Returns
- None
Updates the PFC state.
- conf_create_polycrystal(type, **kwargs)
Creates a polycrystal.
Parameters
- typestr
The type of polycrystal to create (‘circular’ or ‘four_grain’).
- **kwargsdict
Additional arguments for the polycrystal creation, including:
- relaxation_timefloat
The relaxation time to use for the polycrystal creation.
- rotationfloat
The rotation angle for ‘circular’ type (default: pi/6).
- positionarray_like
The position for ‘circular’ type (default: system midpoint).
- radiusfloat
The radius for ‘circular’ type (default: size_min/4).
Returns
- None
Updates the PFC state.
- conf_strain_to_equilibrium()
Strain the PFC to equilibrium by adjusting the position variables and k-space variables.
Parameters
None
Returns
- float
The final strain value that minimizes the free energy.
- evolve_PFC(number_of_steps, method='ETD2RK', suppress_output=False)
Evolves the PFC according to classical PFC dynamics.
Parameters
- number_of_stepsint
The number of steps to evolve the PFC.
- methodstr, optional
The method to use for the evolution, by default ‘ETD2RK’.
- suppress_outputbool, optional
Whether to suppress the progress bar, by default False.
Returns
- None
Updates self.psi and self.psi_f.
- evolve_PFC_hydrodynamic(number_of_steps, method='ETD2RK', gamma_S=0.015625, rho0=0.015625)
Evolves the PFC according to hydrodynamic PFC dynamics.
This requires introducing a velocity field. If psi does not contain this field, it is added to the components psi[1], psi[2], psi[3].
Parameters
- number_of_stepsint
The number of steps to evolve the PFC.
- methodstr, optional
The method to use for the evolution, by default ‘ETD2RK’.
- gamma_Sfloat, optional
The surface tension coefficient, by default 2**-6.
- rho0float, optional
The mass density, by default 2**-6.
Returns
- None
Updates self.psi and self.psi_f.
- evolve_PFC_mechanical_equilibrium(time, Delta_t=10, method='ETD2RK')
Evolves the PFC in mechanical equilibrium.
Parameters
- timefloat
The total time to evolve the PFC.
- Delta_tfloat, optional
The time step for the mechanical equilibrium evolution, by default 10.
- methodstr, optional
The method to use for the evolution, by default ‘ETD2RK’.
Returns
- None
Updates self.psi and self.psi_f.
- plot_PFC(**kwargs)
Plots the PFC.
Parameters
- **kwargsdict
Keyword arguments for the plot. See https://comfitlib.com/ClassBaseSystem/ for a full list of keyword arguments.
Returns
- tuple
A tuple containing (ax, fig), the axes and figure containing the plot.
- plot_field(field, **kwargs)
Plots the PFC.
Parameters
- fieldndarray
The field to plot.
- **kwargsdict
Keyword arguments for the plot. See https://comfitlib.com/ClassBaseSystem/ for a full list of keyword arguments.
Returns
- tuple
A tuple containing (ax, fig), the axes and figure containing the plot.
- plot_orientation_field(orientation_field=None, **kwargs)
Plots the orientation field of the phase-field crystal.
Parameters
- orientation_fieldndarray, optional
The orientation field to plot. If None, it will be calculated.
- **kwargsdict
Keyword arguments for the plot. See https://comfitlib.com/ClassBaseSystem/ for a full list of keyword arguments.
Returns
- tuple
A tuple containing (ax, fig), the axes and figure containing the plot.
- class comfit.phase_field_crystal.phase_field_crystal_1d_periodic.PhaseFieldCrystal1DPeriodic(nx, **kwargs)
Bases:
PhaseFieldCrystal- __init__(nx, **kwargs)
Initializes a phase field crystal system in 1D with a periodic crystal structure.
Parameters
- nxint
The number of unit cells in the x direction.
- **kwargsdict, optional
Additional parameters to configure the system.
Returns
- PhaseFieldCrystal1DPeriodic
The system object representing the simulation.
- calc_L_f()
Calculates the L operator in Fourier space.
Returns
- ndarray
The L operator in Fourier space.
- calc_free_energy_from_proto_amplitudes(psi0, A)
Calculates the free energy of the system from the proto-amplitudes.
Parameters
- psi0float
The average value of psi.
- Afloat
The proto-amplitude.
Returns
- float
The free energy of the system.
- class comfit.phase_field_crystal.phase_field_crystal_2d_square.PhaseFieldCrystal2DSquare(nx, ny, **kwargs)
Bases:
PhaseFieldCrystal- __init__(nx, ny, **kwargs)
Initialize a phase field crystal system in 2D with a square crystal structure.
Parameters
- nxint
The number of unit cells in the x direction.
- nyint
The number of unit cells in the y direction.
- **kwargsdict, optional
- Additional keyword arguments to customize the simulation:
- micro_resolutionlist
Resolution within each unit cell [x, y]
- psi0float
Average value of the density field
- rfloat
Temperature parameter
- tfloat
Parameter related to three-point correlation
- vfloat
Parameter related to four-point correlation
- dtfloat
Time step for simulation
- type_of_evolutionstr
Type of dynamics (‘conserved’ or other)
- for_properties_calculationbool
Whether this instance is for properties calculation
Returns
- PhaseFieldCrystal2DSquare
The system object representing the simulation.
- calc_L_f()
Calculates the L operator in Fourier space.
Parameters
None
Returns
- np.ndarray
The L operator in Fourier space.
- calc_L_sum_f()
Calculate the sum of the L operators in Fourier space. Needed for stress calculation functions.
Returns
- np.ndarray
The sum of the L operators in Fourier space.
- calc_free_energy_from_proto_amplitudes(psi0, A, B)
Calculate the free energy of the system from the proto-amplitudes.
Parameters
- psi0float
The average value of psi.
- Afloat
The first proto-amplitude.
- Bfloat
The second proto-amplitude.
Returns
- float
The free energy of the system.
- calc_proto_amplitude_equations_conserved(vars)
Calculate the equations for the proto-amplitudes for conserved dynamics.
Parameters
- varsarray_like
The proto-amplitudes for the system [A, B].
Returns
- list
The equations for the proto-amplitudes that need to be solved. When both equations equal zero, the amplitudes are at equilibrium.
- calc_proto_amplitudes_conserved()
Calculate the proto-amplitudes for the system.
This method finds the optimal amplitude values (A, B) that minimize the free energy of the phase field crystal system with conserved dynamics.
Returns
- tuple
A tuple containing: - A : float
The first proto-amplitude.
- Bfloat
The second proto-amplitude.
- class comfit.phase_field_crystal.phase_field_crystal_2d_triangular.PhaseFieldCrystal2DTriangular(nx, ny, **kwargs)
Bases:
PhaseFieldCrystal- __init__(nx, ny, **kwargs)
Initializes a phase field crystal system in 2D with a triangular crystal structure.
Parameters
- nxint
The number of unit cells in the x direction.
- nyint
The number of unit cells in the y direction.
- **kwargsdict
Additional arguments to set as attributes, possibly overwriting default values.
Returns
None
- calc_L_f()
Calculates the L operator in Fourier space.
Returns
- np.ndarray
The L operator in Fourier space.
- calc_L_sum_f()
Calculates the sum of the L operators in Fourier space. Needed for stress calculation functions.
Returns
- int
The L operator in Fourier space.
- calc_free_energy_from_proto_amplitudes(psi0, A)
Calculates the free energy of the system from the proto-amplitudes.
Parameters
- psi0float
The average value of psi.
- Afloat
The proto-amplitude.
Returns
- float
The free energy of the system.
- calc_proto_amplitude_equations_unconserved(vars)
Calculates the equations for the proto-amplitudes for the system in the case of conserved dynamics.
Parameters
- varstuple
The proto-amplitudes for the system.
Returns
- list
The equations for the proto-amplitudes for the system.
- class comfit.phase_field_crystal.phase_field_crystal_3d_body_centered_cubic.PhaseFieldCrystal3DBodyCenteredCubic(nx, ny, nz, **kwargs)
Bases:
PhaseFieldCrystal- __init__(nx, ny, nz, **kwargs)
Initializes a phase field crystal system in 3D with a body centered cubic crystal structure.
Parameters
- nxint
The number of unit cells in the x direction.
- nyint
The number of unit cells in the y direction.
- nzint
The number of unit cells in the z direction.
- **kwargsdict
Additional arguments to set as attributes.
Returns
None
- calc_L_f()
Calculate the L operator in Fourier space.
Returns
- numpy.ndarray
The L operator in Fourier space.
- calc_L_sum_f()
Calculate the sum of the L operators in Fourier space. Needed for stress calculation functions.
Returns
- int
The L operator in Fourier space.
- class comfit.phase_field_crystal.phase_field_crystal_3d_face_centered_cubic.PhaseFieldCrystal3DFaceCenteredCubic(nx, ny, nz, **kwargs)
Bases:
PhaseFieldCrystal- __init__(nx, ny, nz, **kwargs)
Initializes a phase field crystal system in 3D with a face centered cubic crystal structure.
Parameters
- nxint
The number of unit cells in the x direction.
- nyint
The number of unit cells in the y direction.
- nzint
The number of unit cells in the z direction.
- **kwargsdict
Additional arguments to set as attributes.
Returns
None
- calc_L_f()
Calculates the L operator in Fourier space.
Returns
- numpy.ndarray
The L operator in Fourier space.
- calc_L_sum_f()
Calculates the sum of the L operators in Fourier space. Needed for stress calculation functions.
Returns
- numpy.ndarray
The L operator in Fourier space.
- calc_free_energy_from_proto_amplitudes(psi0, A, B)
Calculates the free energy of the system from the proto-amplitudes.
Parameters
- psi0float
The average value of psi.
- Afloat
The proto-amplitude.
- Bfloat
The proto-amplitude.
Returns
- float
The free energy of the system.
- calc_proto_amplitude_equations_conserved(vars)
Calculates the equations for the proto-amplitudes for the system in the case of conserved dynamics.
Parameters
- varslist
The proto-amplitudes for the system.
Returns
- list
The equations for the proto-amplitudes for the system in the case of conserved dynamics.
- class comfit.phase_field_crystal.phase_field_crystal_3d_simple_cubic.PhaseFieldCrystal3DSimpleCubic(nx, ny, nz, **kwargs)
Bases:
PhaseFieldCrystal- __init__(nx, ny, nz, **kwargs)
Initializes a phase field crystal system in 3D with a simple cubic crystal structure.
Parameters
- nxint
The number of unit cells in the x direction.
- nyint
The number of unit cells in the y direction.
- nzint
The number of unit cells in the z direction.
- **kwargsdict
Additional arguments to set as attributes.
Returns
None
- calc_L_f()
Calculates the L operator in Fourier space.
Parameters
None
Returns
- numpy.ndarray
The L operator in Fourier space.
- calc_L_sum_f()
Calculates the sum of the L operators in Fourier space. Needed for stress calculation functions.
Parameters
None
Returns
- numpy.ndarray
The L operator in Fourier space.
- calc_free_energy_from_proto_amplitudes(psi0, A, B, C)
Calculates the free energy of the system from the proto-amplitudes.
Parameters
- psi0float
The value of psi0.
- Afloat
The value of A.
- Bfloat
The value of B.
- Cfloat
The value of C.
Returns
- float
The free energy of the system.
- calc_proto_amplitude_equations_conserved(vars)
Calculates the equations for the proto-amplitudes for the system in the case of conserved dynamics.
Parameters
- varslist
The proto-amplitudes for the system.
Returns
- list
The equations for the proto-amplitudes for the system in the case of conserved dynamics.