Skip to content

kups.observables.stress

Stress tensor calculations via virial theorem and lattice vector gradients.

IsMolecularVirialParticles

Bases: HasPositions, HasGroupIndex, HasSystemIndex, Protocol

Particles with position gradients, group and system assignment.

Source code in src/kups/observables/stress.py 
45
46
47
48
49
50
@runtime_checkable
class IsMolecularVirialParticles(HasPositions, HasGroupIndex, HasSystemIndex, Protocol):
    """Particles with position gradients, group and system assignment."""

    @property
    def position_gradients(self) -> Array: ...

IsMolecularVirialState

Bases: IsState[IsMolecularVirialParticles, IsVirialSystems], Protocol

State with groups for molecular virial stress.

Source code in src/kups/observables/stress.py 
53
54
55
56
57
58
59
class IsMolecularVirialState(
    IsState[IsMolecularVirialParticles, IsVirialSystems], Protocol
):
    """State with groups for molecular virial stress."""

    @property
    def groups(self) -> Table[GroupId, HasSystemIndex]: ...

IsVirialParticles

Bases: HasPositions, HasSystemIndex, Protocol

Particles with position gradients ∂U/∂r.

Source code in src/kups/observables/stress.py 
29
30
31
32
33
34
@runtime_checkable
class IsVirialParticles(HasPositions, HasSystemIndex, Protocol):
    """Particles with position gradients ∂U/∂r."""

    @property
    def position_gradients(self) -> Array: ...

IsVirialSystems

Bases: HasUnitCell, Protocol

Systems with unit cell gradients ∂U/∂h.

Source code in src/kups/observables/stress.py 
37
38
39
40
41
42
@runtime_checkable
class IsVirialSystems(HasUnitCell, Protocol):
    """Systems with unit cell gradients ∂U/∂h."""

    @property
    def unitcell_gradients(self) -> UnitCell: ...

lattice_vector_stress_from_state(key, state)

Compute stress from lattice vector gradients from a state.

Source code in src/kups/observables/stress.py 
193
194
195
196
197
198
def lattice_vector_stress_from_state(
    key: Array, state: IsState[IsVirialParticles, IsVirialSystems]
) -> Table[SystemId, Array]:
    """Compute stress from lattice vector gradients from a state."""
    del key
    return stress_via_lattice_vector_gradients(state.systems)

molecular_stress_via_virial_theorem(particles, groups, systems)

Compute molecular virial stress tensor (RASPA convention).

The stress tensor is symmetrized: σ = (σ + σᵀ)/2.

Parameters:

Name Type Description Default
particles Table[ParticleId, IsMolecularVirialParticles]

Per-particle positions, group/system index, and gradients.

 required
groups Table[GroupId, HasSystemIndex]

Per-group system assignment.

 required
systems Table[SystemId, IsVirialSystems]

Per-system unit cell and unit cell gradients.

 required

Returns:

Type Description
Table[SystemId, Array]

Symmetrized stress tensor per system, shape (n_systems, 3, 3).
Source code in src/kups/observables/stress.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
def molecular_stress_via_virial_theorem(
    particles: Table[ParticleId, IsMolecularVirialParticles],
    groups: Table[GroupId, HasSystemIndex],
    systems: Table[SystemId, IsVirialSystems],
) -> Table[SystemId, Array]:
    """Compute molecular virial stress tensor (RASPA convention).

    The stress tensor is symmetrized: σ = (σ + σᵀ)/2.

    Args:
        particles: Per-particle positions, group/system index, and gradients.
        groups: Per-group system assignment.
        systems: Per-system unit cell and unit cell gradients.

    Returns:
        Symmetrized stress tensor per system, shape ``(n_systems, 3, 3)``.
    """
    group_unitcells = systems[groups.data.system].unitcell
    stress = _molecular_stress_via_virial_theorem(
        particles.data.position_gradients,
        systems.data.unitcell_gradients.lattice_vectors,
        particles.data.positions,
        particles.data.group,
        group_unitcells,
        particles.data.system,
        systems.data.unitcell.lattice_vectors,
        systems.data.unitcell.volume,
    )
    return Table(systems.keys, stress)

molecular_virial_stress_from_state(key, state)

Compute molecular virial stress from a state.

Source code in src/kups/observables/stress.py 
209
210
211
212
213
214
215
216
def molecular_virial_stress_from_state(
    key: Array, state: IsMolecularVirialState
) -> Table[SystemId, Array]:
    """Compute molecular virial stress from a state."""
    del key
    return molecular_stress_via_virial_theorem(
        state.particles, state.groups, state.systems
    )

stress_via_lattice_vector_gradients(systems)

Compute stress from energy gradients w.r.t. lattice vectors.

Parameters:

Name Type Description Default
systems Table[SystemId, IsVirialSystems]

Per-system unit cell and unit cell gradients.

 required

Returns:

Type Description
Table[SystemId, Array]

Stress tensor per system, shape (n_systems, 3, 3).
Source code in src/kups/observables/stress.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def stress_via_lattice_vector_gradients(
    systems: Table[SystemId, IsVirialSystems],
) -> Table[SystemId, Array]:
    """Compute stress from energy gradients w.r.t. lattice vectors.

    Args:
        systems: Per-system unit cell and unit cell gradients.

    Returns:
        Stress tensor per system, shape ``(n_systems, 3, 3)``.
    """
    stress = _stress_via_lattice_vector_gradients(
        systems.data.unitcell_gradients.lattice_vectors,
        systems.data.unitcell.volume,
    )
    return Table(systems.keys, stress)

stress_via_virial_theorem(particles, systems)

Compute atomic-level virial stress tensor.

Parameters:

Name Type Description Default
particles Table[ParticleId, IsVirialParticles]

Per-particle positions, system index, and position gradients.

 required
systems Table[SystemId, IsVirialSystems]

Per-system unit cell and unit cell gradients.

 required

Returns:

Type Description
Table[SystemId, Array]

Stress tensor per system, shape (n_systems, 3, 3).
Source code in src/kups/observables/stress.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
def stress_via_virial_theorem(
    particles: Table[ParticleId, IsVirialParticles],
    systems: Table[SystemId, IsVirialSystems],
) -> Table[SystemId, Array]:
    """Compute atomic-level virial stress tensor.

    Args:
        particles: Per-particle positions, system index, and position gradients.
        systems: Per-system unit cell and unit cell gradients.

    Returns:
        Stress tensor per system, shape ``(n_systems, 3, 3)``.
    """
    stress = _stress_via_virial_theorem(
        particles.data.position_gradients,
        systems.data.unitcell_gradients.lattice_vectors,
        particles.data.positions,
        systems.data.unitcell.lattice_vectors,
        particles.data.system,
    )
    return Table(systems.keys, stress)

virial_stress_from_state(key, state)

Compute atomic virial stress from a state.

Source code in src/kups/observables/stress.py 
201
202
203
204
205
206
def virial_stress_from_state(
    key: Array, state: IsState[IsVirialParticles, IsVirialSystems]
) -> Table[SystemId, Array]:
    """Compute atomic virial stress from a state."""
    del key
    return stress_via_virial_theorem(state.particles, state.systems)