SBPath#

This class describes a structural path, i.e. a trajectory of atoms (samson.SBAtom).

You can add, insert, and remove a conformation and parts of a path using samson.SBPath.add(), samson.SBPath.insert(), and samson.SBPath.remove() functions respectively.

You can also add, insert, and remove atoms using samson.SBPath.addAtom(), samson.SBPath.insertAtom(), and samson.SBPath.removeAtom() functions respectively.

You can also get and set position, velocity, and force data for all atoms in a path or for a particular atom.

You can get a node indexer of atoms in the conformation:

# get all paths in the active document
pathIndexer = SAMSON.getNodes('node.type path')

if len(pathIndexer):
        # get the first conformation
        path = pathIndexer[0]

        # get an indexer of atoms in the path
        atomIndexer = path.getAtomIndexer()

You can create a conformation from a path for a particular step:

# create a conformation from the first step in the path
conformationIndexer = path.createConformation(0)
conformation = conformationIndexer[0]
# name the conformation
conformation.name = "Initial state"

# turn the undo system on
with SAMSON.holding("Add new conformation"):
        # hold the cloned folder instance
        SAMSON.hold(conformation)

        # create the cloned folder
        conformation.create()

        # add the conformation to the active document
        SAMSON.getActiveDocument().addChild(conformation)

You can set the current step in a path:

# make the operation undoable
with SAMSON.holding("Change path step"):
        # set the current step of the path to 10
        path.currentStep = 10

You can go through a path to visualize it in SAMSON’s viewport as follows:

# make the operation undoable
with SAMSON.holding("Change path steps"):
        # set the step duration in seconds
        path.stepDuration = SBQuantity.second(0.05)

        # go through all the steps in the path
        for step in range(path.numberOfSteps):
                path.currentStep = step
                # request SAMSON to process events
                SAMSON.processEvents()

See also

SAMSON SDK: SBMStructuralModelPath

class samson.SBPath(*args, **kwargs)#

Bases: SBNode

This class describes a structural path.

Overloaded function.

  1. __init__(self: samson.SBPath) -> None

Constructs a structural model path

  1. __init__(self: samson.SBPath, name: str, nodeIndexer: samson.SBNodeIndexer) -> None

Constructs a structural model path with the given name from the conformations in nodeIndexer.

Parameters:

  • name (str) – A name of the path

  • nodeIndexer (samson.SBNodeIndexer) – An indexer with conformations.

class AnimationType(self: samson.SBPath.AnimationType, value: int)#

Bases: pybind11_object

Members:

Once : Animate once

Loop : Animate in loops

Bounce : Animate in bouncing loops

Bounce = <AnimationType.Bounce: 3>#
Loop = <AnimationType.Loop: 2>#
Once = <AnimationType.Once: 1>#
property name#
property value#
add(*args, **kwargs)#

Overloaded function.

  1. add(self: samson.SBPath, conformation: samson.SBConformation) -> bool

Adds a frame to the path

  1. add(self: samson.SBPath, path: samson.SBPath) -> bool

Adds frames to the path

  1. add(self: samson.SBPath, positionData: list[samson.SBPhysicalVector3], energy: samson.SBQuantity.unitsSI = 0 (dimensionless), time: samson.SBQuantity.unitsSI = 0 (dimensionless), velocityData: list[samson.SBPhysicalVector3] = [], forceData: list[samson.SBPhysicalVector3] = []) -> bool

Adds a frame to the path

  1. add(self: samson.SBPath, positionData: list[list[samson.SBPhysicalVector3]], energyData: list[samson.SBQuantity.unitsSI] = [], timeData: list[samson.SBQuantity.unitsSI] = [], velocityData: list[list[samson.SBPhysicalVector3]] = [], forceData: list[list[samson.SBPhysicalVector3]] = []) -> bool

Adds frames to the path

addAtom(self: samson.SBPath, atom: SBMStructuralModelNodeAtom, atomPositionVector: list[samson.SBPhysicalVector3] = [], atomVelocityVector: list[samson.SBPhysicalVector3] = [], atomForceVector: list[samson.SBPhysicalVector3] = []) → bool#

Adds an atom to the path

clearSourceFileName(self: samson.SBPath) → None#

Clears the source file name.

copy(self: samson.SBPath, firstStep: int, lastStep: int) → samson.SBPath#

Copies frames from the path to create a new path

createConformation(self: samson.SBPath, step: int) → samson.SBNodeIndexer#

Create a conformation corresponding to a specific step

createConformations(self: samson.SBPath) → samson.SBNodeIndexer#

Create conformations corresponding to all steps

createStructuralModels(*args, **kwargs)#

Overloaded function.

  1. createStructuralModels(self: samson.SBPath, step: int) -> samson.SBNodeIndexer

Create structural models corresponding to a specific step

  1. createStructuralModels(self: samson.SBPath) -> samson.SBNodeIndexer

Create structural models corresponding to all steps

getAtomIndexer(self: samson.SBPath) → samson.SBNodeIndexer#

Returns the indexer of atoms for which a position is saved.

Returns:

A node indexer with the associated atoms.

Return type:

samson.SBNodeIndexer

getEnergy(self: samson.SBPath, step: int) → samson.SBQuantity.unitsSI#

Returns the energy for a specific step

getEnergyData(self: samson.SBPath) → list[samson.SBQuantity.unitsSI]#

Returns the energy data: 1D array, size = (number of timesteps)

getForce(*args, **kwargs)#

Overloaded function.

  1. getForce(self: samson.SBPath, step: int, atomIndex: int) -> samson.SBPhysicalVector3

Returns force of atom with atomIndex for a specific step

  1. getForce(self: samson.SBPath, step: int, atom: SBMStructuralModelNodeAtom) -> samson.SBPhysicalVector3

Returns force of atom for a specific step

getForceData(self: samson.SBPath) → list[list[samson.SBPhysicalVector3]]#

Returns force data: 2D array, size = (number of timesteps) x (number of atoms)

getMass(*args, **kwargs)#

Overloaded function.

  1. getMass(self: samson.SBPath, atomIndex: int) -> samson.SBQuantity.unitsSI

Returns mass of atom with atomIndex.

  1. getMass(self: samson.SBPath, atom: SBMStructuralModelNodeAtom) -> samson.SBQuantity.unitsSI

Returns mass of atom.

getMassData(self: samson.SBPath) → list[samson.SBQuantity.unitsSI]#

Returns mass data for all atoms: 1D array, size = (number of atoms).

getNextPath(self: samson.SBPath) → samson.SBPath#

Returns the next path in the document

getPosition(*args, **kwargs)#

Overloaded function.

  1. getPosition(self: samson.SBPath, step: int, atomIndex: int) -> samson.SBPhysicalVector3

Returns position of atom with atomIndex for a specific step

  1. getPosition(self: samson.SBPath, step: int, atom: SBMStructuralModelNodeAtom) -> samson.SBPhysicalVector3

Returns position of atom for a specific step

getPositionData(self: samson.SBPath) → list[list[samson.SBPhysicalVector3]]#

Returns position data: 2D array, size = (number of timesteps) x (number of atoms)

getPreviousPath(self: samson.SBPath) → samson.SBPath#

Returns the previous path in the document

getTime(self: samson.SBPath, step: int) → samson.SBQuantity.unitsSI#

Returns the time for a specific step

getTimeData(self: samson.SBPath) → list[samson.SBQuantity.unitsSI]#

Returns the time data: 1D array, size = (number of timesteps)

getUnitCell(self: samson.SBPath, step: int) → samson.SBUnitCell#

Returns unit-cell data for a specific step.

getUnitCellData(self: samson.SBPath) → list[samson.SBUnitCell]#

Returns unit-cell data for all steps: 1D array, size = (number of timesteps).

getUnwrappedPosition(*args, **kwargs)#

Overloaded function.

  1. getUnwrappedPosition(self: samson.SBPath, step: int, atomIndex: int) -> samson.SBPhysicalVector3

Returns the unwrapped position of atom with atomIndex for a specific step.

  1. getUnwrappedPosition(self: samson.SBPath, step: int, atom: SBMStructuralModelNodeAtom) -> samson.SBPhysicalVector3

Returns the unwrapped position of atom for a specific step.

getVelocity(*args, **kwargs)#

Overloaded function.

  1. getVelocity(self: samson.SBPath, step: int, atomIndex: int) -> samson.SBPhysicalVector3

Returns velocity of atom with atomIndex for a specific step

  1. getVelocity(self: samson.SBPath, step: int, atom: SBMStructuralModelNodeAtom) -> samson.SBPhysicalVector3

Returns velocity of atom for a specific step

getVelocityData(self: samson.SBPath) → list[list[samson.SBPhysicalVector3]]#

Returns velocity data: 2D array, size = (number of timesteps) x (number of atoms)

hasEnergyData(self: samson.SBPath) → bool#

Returns whether the path has energy data

hasForceData(self: samson.SBPath) → bool#

Returns whether the path has force data

hasMassData(self: samson.SBPath) → bool#

Returns whether the path has mass data

hasPositionData(self: samson.SBPath) → bool#

Returns whether the path has position data

hasTimeData(self: samson.SBPath) → bool#

Returns whether the path has time data

hasUnitCellData(self: samson.SBPath) → bool#

Returns whether the path has unit cell data

hasVelocityData(self: samson.SBPath) → bool#

Returns whether the path has velocity data

insert(*args, **kwargs)#

Overloaded function.

  1. insert(self: samson.SBPath, step: int, conformation: samson.SBConformation) -> bool

Inserts a frame to the path at the step

  1. insert(self: samson.SBPath, step: int, path: samson.SBPath) -> bool

Inserts frames to the path starting from the step

  1. insert(self: samson.SBPath, step: int, positionData: list[samson.SBPhysicalVector3], energy: samson.SBQuantity.unitsSI = 0 (dimensionless), time: samson.SBQuantity.unitsSI = 0 (dimensionless), velocityData: list[samson.SBPhysicalVector3] = [], forceData: list[samson.SBPhysicalVector3] = []) -> bool

Inserts a frame in the path at position step

  1. insert(self: samson.SBPath, step: int, positionData: list[list[samson.SBPhysicalVector3]], energyData: list[samson.SBQuantity.unitsSI] = [], timeData: list[samson.SBQuantity.unitsSI] = [], velocityData: list[list[samson.SBPhysicalVector3]] = [], forceData: list[list[samson.SBPhysicalVector3]] = []) -> bool

Inserts frames in the path at position step

insertAtom(self: samson.SBPath, atomIndex: int, atom: SBMStructuralModelNodeAtom, atomPositionVector: list[samson.SBPhysicalVector3] = [], atomVelocityVector: list[samson.SBPhysicalVector3] = [], atomForceVector: list[samson.SBPhysicalVector3] = []) → bool#

Inserts an atom at index atomIndex to the path

makeWholeAllSteps(self: samson.SBPath) → bool#

Reconstructs bond-connected components across periodic boundaries for all steps.

makeWholeStep(self: samson.SBPath, step: int) → bool#

Reconstructs bond-connected components across periodic boundaries for one step.

remove(*args, **kwargs)#

Overloaded function.

  1. remove(self: samson.SBPath, step: int) -> samson.SBConformation

Remove a frame from the path to create a conformation

  1. remove(self: samson.SBPath, firstStep: int, lastStep: int) -> samson.SBPath

Removes frames from the path to create a new path

removeAtom(self: samson.SBPath, atom: SBMStructuralModelNodeAtom) → bool#

Removes an atom from the path

setEnergy(self: samson.SBPath, step: int, energy: samson.SBQuantity.unitsSI) → None#

Sets the energy for a specific step

setEnergyData(self: samson.SBPath, energyData: list[samson.SBQuantity.unitsSI]) → None#

Sets the energy data: 1D array, size = (number of timesteps)

setForce(*args, **kwargs)#

Overloaded function.

  1. setForce(self: samson.SBPath, step: int, atomIndex: int, force: samson.SBPhysicalVector3) -> None

Sets force of atom with atomIndex for a specific step

  1. setForce(self: samson.SBPath, step: int, atom: SBMStructuralModelNodeAtom, force: samson.SBPhysicalVector3) -> None

Sets force of atom for a specific step

setForceData(self: samson.SBPath, forceData: list[list[samson.SBPhysicalVector3]]) → None#

Sets force data: 2D array, size = (number of timesteps) x (number of atoms)

setMass(*args, **kwargs)#

Overloaded function.

  1. setMass(self: samson.SBPath, atomIndex: int, mass: samson.SBQuantity.unitsSI) -> None

Sets mass of atom with atomIndex.

  1. setMass(self: samson.SBPath, atom: SBMStructuralModelNodeAtom, mass: samson.SBQuantity.unitsSI) -> None

Sets mass of atom.

setMassData(self: samson.SBPath, massData: list[samson.SBQuantity.unitsSI]) → None#

Sets mass data for all atoms: 1D array, size = (number of atoms).

setPosition(*args, **kwargs)#

Overloaded function.

  1. setPosition(self: samson.SBPath, step: int, atomIndex: int, position: samson.SBPhysicalVector3) -> None

Sets position of atom with atomIndex for a specific step

  1. setPosition(self: samson.SBPath, step: int, atom: SBMStructuralModelNodeAtom, position: samson.SBPhysicalVector3) -> None

Sets position of atom for a specific step

setPositionData(self: samson.SBPath, positionData: list[list[samson.SBPhysicalVector3]]) → None#

Sets position data: 2D array, size = (number of timesteps) x (number of atoms)

setTime(self: samson.SBPath, step: int, time: samson.SBQuantity.unitsSI) → None#

Sets the time for a specific step

setTimeData(self: samson.SBPath, timeData: list[samson.SBQuantity.unitsSI]) → None#

Sets the time data: 1D array, size = (number of timesteps)

setUnitCell(self: samson.SBPath, step: int, unitCell: samson.SBUnitCell) → None#

Sets unit-cell data for a specific step.

setUnitCellData(self: samson.SBPath, unitCellData: list[samson.SBUnitCell]) → None#

Sets unit-cell data for all steps: 1D array, size = (number of timesteps).

setVelocity(*args, **kwargs)#

Overloaded function.

  1. setVelocity(self: samson.SBPath, step: int, atomIndex: int, velocity: samson.SBPhysicalVector3) -> None

Sets velocity of atom with atomIndex for a specific step

  1. setVelocity(self: samson.SBPath, step: int, atom: SBMStructuralModelNodeAtom, velocity: samson.SBPhysicalVector3) -> None

Sets velocity of atom for a specific step

setVelocityData(self: samson.SBPath, velocityData: list[list[samson.SBPhysicalVector3]]) → None#

Sets velocity data: 2D array, size = (number of timesteps) x (number of atoms)

unwrap(self: samson.SBPath) → bool#

Unwraps the trajectory over time using successive minimum-image displacements.

updateState(self: samson.SBPath) → None#

Updates the state along the path according to the animation parameters

wrapAllSteps(self: samson.SBPath, keepConnectedComponentsWhole: bool = True) → bool#

Wraps positions of all steps into primary unit cells.

wrapStep(self: samson.SBPath, step: int, keepConnectedComponentsWhole: bool = True) → bool#

Wraps positions of one step into the primary unit cell.

Bounce = <AnimationType.Bounce: 3>#
Loop = <AnimationType.Loop: 2>#
Once = <AnimationType.Once: 1>#
property animationFlag#

The animation flag

property animationType#

The animation type

property currentEnergy#

The current energy

property currentStep#

The current step along the path

property currentTime#

The current time

property forwardFlag#

The forward flag, which indicates when the animation is moving forward

property hasSourceFileName#

Returns whether the source file name is set.

property numberOfAtoms#

The number of atoms for which a position is saved

property numberOfFrames#

numberOfSteps

Type:

The number of steps/frames in the path. Alias

property numberOfSteps#

numberOfFrames

Type:

The number of steps/frames in the path. Alias

property smoothingWindowSize#

The size of the smoothing window

property sourceFileName#

The source file name

property stepDuration#

The step duration

property stride#

The animation stride