cmmdft package

Submodules

cmmdft.calculator module

cmmdft.eos module

cmmdft.free_energy module

cmmdft.functionals module

cmmdft.grid module

Tools to perform classical DFT simulations

class cmmdft.grid.Cell(rvecs)[source]

Bases: object

Simulation cell with periodicity information.

Represents the simulation box geometry defined by lattice vectors, and provides coordinate transformation utilities. Supports orthogonal and non-orthogonal (triclinic) cells.

rvecs

Lattice vectors as rows: [[a_x, a_y, a_z],: [b_x, b_y, b_z], [c_x, c_y, c_z]]

Type:: ndarray

volume

Cell volume

Type:: float

lengths

Lengths of lattice vectors (a, b, c)

Type:: tuple

angles

Angles between lattice vectors in degrees (alpha, beta, gamma)

Type:: tuple

parameters

(lengths, angles) tuple

Type:: tuple

inv_rvecs

Inverse of the lattice vector matrix

Type:: ndarray

__init__(rvecs)[source]

Initialize a simulation cell.

Parameters:: rvecs (array_like) – 3x3 matrix of lattice vectors as rows, shape (3, 3)

cart_to_frac(cart_coords)[source]

Convert Cartesian coordinates to fractional (reduced) coordinates.

Parameters:: cart_coords (array_like) – Cartesian coordinates with shape (…, 3)
Returns:: Fractional coordinates with same shape as input, where each coordinate is expressed as a linear combination of lattice vectors
Return type:: ndarray

Examples

>>> cell = Cell(np.eye(3) * 5.0)
>>> frac = cell.cart_to_frac([2.5, 2.5, 2.5])
>>> np.allclose(frac, [0.5, 0.5, 0.5])
True

copy()[source]

Create a deep copy of the cell.

Returns:: Independent copy of this cell object
Return type:: Cell

frac_to_cart(frac_coords)[source]

Convert fractional (reduced) coordinates to Cartesian coordinates.

Parameters:: frac_coords (array_like) – Fractional coordinates with shape (…, 3), where last dimension contains fractional coordinates in basis of lattice vectors
Returns:: Cartesian coordinates with same shape as input
Return type:: ndarray

Examples

>>> cell = Cell(np.eye(3) * 5.0)
>>> cart = cell.frac_to_cart([0.5, 0.5, 0.5])
>>> np.allclose(cart, [2.5, 2.5, 2.5])
True

mic(delta_cart)[source]

Apply the minimum image convention (MIC) to displacement vectors.

Maps displacement vectors to their nearest periodic images by converting to fractional coordinates, wrapping to [-0.5, 0.5), and converting back to Cartesian.

Parameters:: delta_cart (array_like) – Cartesian displacement vectors with shape (…, 3), where last dimension contains the 3D displacement
Returns:: Shortest displacement vectors under periodic boundary conditions, same shape as input
Return type:: ndarray
Raises:: ValueError – If last dimension is not size 3

Notes

Essential for simulating systems with periodic boundary conditions. Ensures distances are calculated using periodic neighbors.

Examples

>>> cell = Cell(np.eye(3) * 10.0)
>>> delta = cell.mic([8.0, 0.0, 0.0])  # > a/2
>>> np.allclose(np.linalg.norm(delta), 2.0)  # Should wrap to -2
True

class cmmdft.grid.Grid(cell, npoints=None, spacing=0.472431533480313)[source]

Bases: object

Discrete spatial grid for classical DFT calculations.

Discretizes the simulation domain into real-space and reciprocal-space grids for efficient computation of functionals and Fourier transforms. Provides integration and FFT operations on fields defined on the grid.

Note: Be aware that FFT efficiency depends heavily on the number of points, preferably choose powers of 2.

cell

Cell object defining the simulation domain

Type:: Cell

npoints

Number of grid points in each direction [nx, ny, nz]

Type:: ndarray

spacings

Grid spacing in each direction (Angstrom)

Type:: ndarray

points

Real-space grid point coordinates with shape (nx, ny, nz, 4), where last dimension contains [x, y, z, r]

Type:: ndarray

kpoints

Reciprocal-space grid point coordinates with shape (nx, ny, nz, 4), where last dimension contains [kx, ky, kz, \(|k|\)]

Type:: ndarray

dr

Volume element in real space

Type:: float

dk

Volume element in reciprocal space

Type:: float

sigma_lanczos

Lanczos kernel for FFT to reduce Gibbs phenomenon

Type:: ndarray

__init__(cell, npoints=None, spacing=0.472431533480313)[source]

Initialize a discrete spatial grid.

Parameters:

cell (Cell) – Cell object defining the simulation domain
npoints (int or list, optional) – Grid dimensions [nx, ny, nz]. If a single integer is given, equal dimensions in each direction are assumed. If None, grid points are determined from cell dimensions and spacing. Default is None
spacing (float, optional) – Spacing between grid points in Angstrom. Only used to determine npoints if npoints is None. Default is 0.25 Angstrom

copy()[source]

Create a deep copy of the grid.

Returns:: Independent copy of this grid object
Return type:: Grid

fft(rdata)[source]

Fast Fourier transform a real-space field with phase correction.

Applies FFT with phase factor correction. Legacy method for single-component grids with shape (nx, ny, nz). For fields with additional dimensions, use fftn() instead.

Parameters:: rdata (ndarray) – Real-space field with shape (nx, ny, nz)
Returns:: Reciprocal-space field (complex)
Return type:: ndarray

See also

fftn: More general FFT supporting arbitrary dimensions
ifft: Inverse FFT

fftn(rdata)[source]

Fourier transform along the 3 spatial axes with phase correction.

Applies FFT with phase factor correction and supports fields with arbitrary leading/trailing dimensions beyond the spatial block.

Parameters:: rdata (ndarray) – Real-space field with spatial dimensions (nx, ny, nz) anywhere in the shape, e.g.: (N,N,N), (N,N,N,M), (M,N,N,N), (M1,N,N,N,M2)
Returns:: Reciprocal-space field (complex) with same shape as input
Return type:: ndarray
Raises:: ValueError – If spatial block (nx, ny, nz) is not found in input shape

See also

fft: Legacy method for simple (N,N,N) shaped grids
ifftn: Inverse FFT

ifft(fdata)[source]

Inverse Fourier transform a reciprocal-space field with phase correction.

Applies inverse FFT with phase factor correction. Legacy method for single-component grids with shape (nx, ny, nz). For fields with additional dimensions, use ifftn() instead.

Parameters:: fdata (ndarray) – Reciprocal-space field (complex) with shape (nx, ny, nz)
Returns:: Real-space field (real values)
Return type:: ndarray

See also

ifftn: More general inverse FFT supporting arbitrary dimensions
fft: Forward FFT

ifftn(fdata)[source]

Inverse Fourier transform along the 3 spatial axes with phase correction.

Applies inverse FFT with phase factor correction and supports fields with arbitrary leading/trailing dimensions beyond the spatial block.

Parameters:: fdata (ndarray) – Reciprocal-space field (complex) with spatial dimensions (nx, ny, nz) anywhere in the shape, e.g.: (N,N,N), (N,N,N,M), (M,N,N,N), etc.
Returns:: Real-space field (real values) with same shape as input
Return type:: ndarray
Raises:: ValueError – If spatial block (nx, ny, nz) is not found in input shape

See also

ifft: Legacy method for simple (N,N,N) shaped grids
fftn: Forward FFT

integrate(data)[source]

Integrate a field over the entire grid domain.

Parameters:: data (ndarray) – Field values with spatial dimensions (nx, ny, nz)
Returns:: Integral of the field over the domain
Return type:: float or complex

integrate_n(data)[source]

Integrate a field over the entire grid domain.

Integrates along the 3 spatial axes (matching self.npoints). Supports fields with arbitrary leading/trailing dimensions.

Parameters:: data (ndarray) – Field values with spatial dimensions (nx, ny, nz) anywhere in the shape. Supports arbitrary leading/trailing dimensions
Returns:: Integral of the field over the domain
Return type:: float or complex
Raises:: ValueError – If spatial block (nx, ny, nz) is not found in input shape

supercell(supercell)[source]

Create a supercell grid with repeated unit cells.

Parameters:: supercell (array_like) – Repetition factors [nx, ny, nz] for each lattice vector
Returns:: New Grid object for the expanded supercell
Return type:: Grid

cmmdft.guest_dict module

cmmdft.integrate_flexibility module

cmmdft.log module

cmmdft.plotter module

cmmdft.program module

cmmdft.solver module

cmmdft.system module

cmmdft.tools module

cmmdft.units_constants module

class cmmdft.units_constants.convert_units(mass_guest, mass_host, volume_host)[source]

Bases: object

__init__(mass_guest, mass_host, volume_host)[source]

conversion_factor(input='mol/mol', output='mol/mol')[source]

input: a string of the unit of the input

output: a string of the desired unit output

supported adorption units: wt%, cm3/cm3, mol/mol, mol/g, mol/kg

cmmdft.units_constants.parse_unit(expression)[source]

Evaluate a python expression string containing constants

Argument:: expression – A string containing a numerical expressions including unit conversions.

cmmdft.external_potential package

The external potential utilities are part of the main package API and are included here alongside the rest of the CmmDFT modules.

cmmdft.external_potential.extpot_calculator module

cmmdft.external_potential.interpolator module

cmmdft.external_potential.parameters module

Object-oriented representation of parameter files

class cmmdft.external_potential.parameters.Complain(filename='__nofile__')[source]

Bases: object

Class for complain method of ParameterFile and ParameterSection

class cmmdft.external_potential.parameters.ParameterDefinition(suffix, lines=None, complain=None)[source]

Bases: object

Object that represents a set of data lines from a parameter file

copy()[source]

class cmmdft.external_potential.parameters.ParameterSection(prefix, definitions=None, complain=None)[source]

Bases: object

Object that represents one section in a force field parameter file

copy()[source]: Return an independent copy

class cmmdft.external_potential.parameters.Parameters(sections=None)[source]

Bases: object

Object that represents a force field parameter file

The parameter file is first parsed by this object into a convenient data structure with dictionaries. The actual force field is then generated based on these dictionaries.

The parameter file has a purely line-based syntax. The order of the lines has no meaning. Comments begin with a hash sign (#) and continue till the end of a line. If the line is empty after stripping the comments, it is ignored. Every non-empty line should have the following format:

PREFIX:SUFFIX DATA

The prefix is used for sections, the suffix for definitions and the remainder of the line contains arguments for the definition. Definitions may be repeated with different or the same arguments.

copy()[source]: Return an independent copy

classmethod from_file(filenames)[source]

Create a Parameters instance from one or more text files.

Arguments:

filenames: A single filename or a list of filenames

write_to_file(filename)[source]

Write the parameters back to a file

The outut file will not contain any comments.

cmmdft package

Submodules

cmmdft.calculator module

cmmdft.eos module

cmmdft.free_energy module

cmmdft.functionals module

cmmdft.grid module

cmmdft.guest_dict module

cmmdft.integrate_flexibility module

cmmdft.log module

cmmdft.plotter module

cmmdft.program module

cmmdft.solver module

cmmdft.system module

cmmdft.tools module

cmmdft.units_constants module

cmmdft.external_potential package

cmmdft.external_potential.extpot_calculator module

cmmdft.external_potential.interpolator module

cmmdft.external_potential.parameters module

cmmdft.external_potential.utils module

Module contents