Tissue Forge Library Python API Reference

This is the API Reference page for the module: tissue_forge

tissue_forge.init(*args, **kwargs)

Initialize a simulation in Python

Parameters:
  • args (PyObject) – positional arguments; first argument is name of simulation (if any)

  • kwargs (PyObject) –

    keyword arguments; currently supported are

    dim: (3-component list of floats) the dimensions of the spatial domain; default is [10., 10., 10.]

    cutoff: (float) simulation cutoff distance; default is 1.

    cells: (3-component list of ints) the discretization of the spatial domain; default is [4, 4, 4]

    threads: (int) number of threads; default is hardware maximum

    flux_steps: (int) number of flux steps per simulation step; default is 1

    integrator: (int) simulation integrator; default is FORWARD_EULER

    dt: (float) time discretization; default is 0.01

    bc: (int or dict) boundary conditions; default is everywhere periodic

    window_size: (2-component list of ints) size of application window; default is [800, 600]

    throw_exc: (bool) whether errors raise exceptions; default is False

    seed: (int) seed for pseudo-random number generator

    load_file: (str) path to saved simulation state to initialize

    logger_level: (int) logger level; default is no logging

    clip_planes: (list of tuple of (FVector3, FVector3)) list of point-normal pairs of clip planes; default is no planes

tissue_forge.run(*args, **kwargs)

Runs the event loop until all windows close or simulation time expires. Automatically performs universe time propagation.

Parameters:

args (float) – period to execute, in units of simulation time (default runs infinitely)

tissue_forge.irun()

Alias of tissue_forge.tissue_forge.Simulator.irun

tissue_forge.close()

Alias of tissue_forge.tissue_forge.Simulator.close

tissue_forge.show()

Alias of tissue_forge.tissue_forge.Simulator.show

tissue_forge.step(until: float = 0)

Alias of tissue_forge.tissue_forge.Universe.step

tissue_forge.stop()

Alias of tissue_forge.tissue_forge.Universe.stop

tissue_forge.start()

Alias of tissue_forge.tissue_forge.Universe.start

tissue_forge.throw_exceptions(_throw: bool)

Set whether errors result in exceptions

tissue_forge.throwing_exceptions() bool

Test whether errors result in exceptions

class tissue_forge.version
build_date

Package build date

compiler

Package compiler ID

compiler_version

Package compiler version

major

Tissue Forge major version

minor

Tissue Forge minor version

patch

Tissue Forge patch version

system_name

System name

system_version

System version

version

Tissue Forge version

tissue_forge.has_cuda
Type:

boolean

Flag signifying whether CUDA support is installed.

Simulator

class tissue_forge.SimulatorInterface
static close()

Closes the main window, while the application / simulation continues to run.

property cuda_config

CUDA runtime interface, if any

static irun()

Interactive python version of the run loop. This checks the ipython context and lets ipython process keyboard input, while we also running the simulator and processing window messages.

static redraw()

Redraw the scene

static run(*args, **kwargs)

Runs the event loop until all windows close or simulation time expires. Automatically performs universe time propagation.

Parameters:

args (double) – period to execute, in units of simulation time (default runs infinitely)

static show()

Shows any windows that were specified in the config. This works just like MatPlotLib’s show method. The show method does not start the universe time propagation unlike run and irun.

property threads: int

Number of threads

property throw_exceptions: bool

Whether errors result in exceptions

tissue_forge.Simulator
Type:

SimulatorInterface

Simulator runtime interface

Universe

class tissue_forge.UniverseInterface
property angles

All angles in the universe

property bonds

All bonds in the universe

property boundary_conditions

Boundary conditions

property center: fVector3

Universe center point

property cutoff: float

Global interaction cutoff distance

property dihedrals

All dihedrals in the universe

property dim: fVector3

Universe dimensions

property dt

Time step

property flux_steps: int

Number of flux steps per simulation step

grid(shape)

Gets a three-dimesional array of particle lists, of all the particles in the system.

Parameters:

shape – shape of grid

Returns:

three-dimension array of particle lists according to discretization and location

property kinetic_energy

Universe kinetic energy

property name: str

name of the model / script

property num_types: int

Number of particle types

property particles

Gets all particles in the universe

Return type:

ParticleList

reset_species()

Reset all species in all particles

start()

Starts the universe time evolution, and advanced the universe forward by timesteps in dt. All methods to build and manipulate universe objects are valid whether the universe time evolution is running or stopped.

step(until: float = 0)

Performs a single time step of the universe if no arguments are given. Optionally runs until until.

Parameters:

until – period to execute, in units of simulation time (default executes one time step).

stop()

Stops the universe time evolution. This essentially freezes the universe, everything remains the same, except time no longer moves forward.

property temperature

Universe temperature

property time

Current time

virial(origin=None, radius: float | None = None, types=None) fMatrix3

Computes the virial tensor for the either the entire simulation domain, or a specific local virial tensor at a location and radius. Optionally can accept a list of particle types to restrict the virial calculation for specify types.

Parameters:
  • origin – An optional length-3 array for the origin. Defaults to the center of the simulation domain if not given.

  • radius – An optional number specifying the size of the region to compute the virial tensor for. Defaults to the entire simulation domain.

  • types – An optional list of Particle types to include in the calculation. Defaults to every particle type.

Returns:

virial tensor

property volume: float

Universe volume

tissue_forge.Universe
Type:

UniverseInterface

Universe runtime interface

Boundary Conditions

class tissue_forge.BoundaryCondition

A condition on a boundary of the universe.

property kind_str: str

The name of the kind of boundary condition.

restore

restoring percent.

When objects hit this boundary, they get reflected back at restore percent, so if restore is 0.5, and object hitting the boundary at 3 length / time recoils with a velocity of 1.5 lengths / time.

velocity

the velocity on the boundary

name

name of the boundary

normal

vector normal to the boundary

class tissue_forge.BoundaryConditions(*args)

The BoundaryConditions class serves as a container for the six instances of the BoundaryCondition object

left

The left boundary

right

The right boundary

front

The front boundary

back

The back boundary

bottom

The bottom boundary

top

The top boundary

static bounded_position(*args)

Overload 1:

Enforce boundary conditions on a position


Overload 2:

Enforce boundary conditions on a position

toString()

Get a JSON string representation

Return type:

string

Returns:

std::string

static fromString(str)

Create from a JSON string representation.

Parameters:

str (string) –

Return type:

BoundaryConditions

Returns:

BoundaryConditions*

__reduce__()

Helper for pickle.

Constants

Geometry Constants

class tissue_forge.PointsType(value)

An enumeration.

Cube

Unit hollow cube

Disk

Unit disk

Ring

Unit ring

SolidCube

Unit solid cube

SolidSphere

Unit sphere shell

Sphere

Unit sphere

Boundary Condition Constants

tissue_forge.BOUNDARY_NONE

no boundary conditions

tissue_forge.PERIODIC_X

periodic in the x (first) direction

tissue_forge.PERIODIC_Y

periodic in the y (second) direction

tissue_forge.PERIODIC_Z

periodic in the z (third) direction

tissue_forge.PERIODIC_FULL

periodic in the all directions

tissue_forge.FREESLIP_X

free slip in the x (first) direction

tissue_forge.FREESLIP_Y

free slip in the y (second) direction

tissue_forge.FREESLIP_Z

free slip in the z (third) direction

tissue_forge.FREESLIP_FULL

free slip in the all directions

Integrator Constants

tissue_forge.FORWARD_EULER

Integrator constant: Forward Euler.

Recommended, most tested, standard single-step.

tissue_forge.RUNGE_KUTTA_4

Integrator constant: Runge-Kutta.

Experimental Runge-Kutta-4.

Particle Dynamics Constants

tissue_forge.Newtonian

Newtonian dynamics.

tissue_forge.Overdamped

Overdamped dynamics.

Potential Constants

tissue_forge.Potential.Kind.potential

Potential kind

tissue_forge.Potential.Kind.dpd

Dissipative particle dynamics kind

Particles and Clusters

class tissue_forge.Particle

The particle data structure.

Instance vars for each particle.

Note that the arrays for x, v and f are 4 entries long for proper alignment.

All particles are stored in a series of contiguous blocks of memory that are owned by the space cells. Each space cell has a array of particle structs.

If you’re building a model, you should probably instead be working with a ParticleHandle.

handle()

Get a handle for this particle.

toString()

Get a JSON string representation

static fromString(str)

Create from a JSON string representation.

The returned particle is not automatically registered with the engine.

To properly register a particle from a string, pass the string to the particle constructor of the appropriate particle type or cluster.

Parameters:

str (string) – constructor string, as returned by toString

Return type:

Particle

Returns:

unregistered particle

__reduce__()

Helper for pickle.

class tissue_forge.ParticleHandle(*args)

A handle to a particle.

The engine allocates particle memory in blocks, and particle values get moved around all the time, so their addresses change.

The partlist is always ordered by id, i.e. partlist[id] always points to the same particle, even though that particle may move from cell to cell.

This is a safe way to work with a particle.

property charge

Particle charge

property mass

Particle mass

property frozen

Particle frozen flag

property frozen_x

Particle frozen flag along x

property frozen_y

Particle frozen flag along y

property frozen_z

Particle frozen flag along z

property style

Particle style

property age

Particle age

property radius

Particle radius

property volume

Particle volume

property name

Particle name

property position

Particle position

property velocity

Particle velocity

property force

Net force acting on particle

property force_init

Persistent force acting on particle

property id

Particle id

property type_id

Particle type id

property cluster_id

Cluster particle id, if any; -1 if particle is not in a cluster

property species

Particle species

property bonds

Bonds attached to particle

property angles

Angles attached to particle

property dihedrals

Dihedrals attached to particle

part()

Gets the actual particle of this handle.

Return type:

Particle

Returns:

particle, if available

get()

Gets the actual particle of this handle.

Alias for consistency with other objects.

type()

Gets the particle type of this handle.

split(*args)

Overload 1:

Splits a single particle into two.

The new particle is placed along a randomly selected orientation.

The two resulting particles have the same mass and volume.

If species are attached to the split particle, then the amount of species is allocated to the two resulting particles such that their species concentrations are the same as the split particle. Species are conserved.

The two resulting particles have the type of the split particle.

The two resulting particles are placed in contact.

The center of mass of the two resulting particles is the same as that of the split particle.

The combined mass and volume of the two resulting particles are the same as those of the split particle.

Return type:

ParticleHandle

Returns:

new particle


Overload 2:

Splits a single particle into two along a given direction.

The new particle is placed along the orientation of the passed direction.

The two resulting particles have the same mass and volume.

If species are attached to the split particle, then the amount of species is allocated to the two resulting particles such that their species concentrations are the same as the split particle. Species are conserved.

The two resulting particles have the type of the split particle.

The two resulting particles are placed in contact.

The center of mass of the two resulting particles is the same as that of the split particle.

The combined mass and volume of the two resulting particles are the same as those of the split particle.

Parameters:

childDirection (FVector3) – direction along which the particle is split.

Return type:

ParticleHandle

Returns:

new particle


Overload 3:

Splits a single particle into two with sizes according to a given ratio.

The new particle is placed along a randomly selected orientation.

The new particle has a mass and volume equal to those of the split particle multiplied by a ratio.

If species are attached to the split particle, then the amount of species is allocated to the two resulting particles such that their species concentrations are the same as the split particle. Species are conserved.

The two resulting particles have the type of the split particle.

The two resulting particles are placed in contact.

The center of mass of the two resulting particles is the same as that of the split particle.

The combined mass and volume of the two resulting particles are the same as those of the split particle.

Parameters:

childRatio (float) – ratio of the child particle volume to the split particle volume. Must be in (0, 1).

Return type:

ParticleHandle

Returns:

new particle


Overload 4:

Splits a single particle into two and allocates species according to given ratios.

The new particle is placed along a randomly selected orientation.

The two resulting particles have the same mass and volume.

If species are attached to the split particle, then the amount of species is allocated to the two resulting particles such that the total amount in the new particles is equal to the total amount of the split particle multiplied by a ratio. Species are conserved.

The two resulting particles have the type of the split particle.

The two resulting particles are placed in contact.

The center of mass of the two resulting particles is the same as that of the split particle.

The combined mass and volume of the two resulting particles are the same as those of the split particle.

Parameters:

speciesRatios (std::vector< FPTYPE,std::allocator< FPTYPE > >) – ratio of the child particle total species amount to the split particle total species amount. Each must be in (0, 1).

Return type:

ParticleHandle

Returns:

new particle


Overload 5:

Splits a single particle into two along a given direction, with sizes according to a given ratio, and and optionally with different resulting particle types.

The new particle is placed along the orientation of the passed direction.

The new particle has a mass and volume equal to those of the split particle multiplied by a ratio.

If species are attached to the split particle, then the amount of species is allocated to the two resulting particles such that the total amount in the new particles is equal to the total amount of the split particle multiplied by a ratio. Species are conserved.

The two resulting particles have the type of the split particle unless otherwise specified.

The two resulting particles are placed in contact.

The center of mass of the two resulting particles is the same as that of the split particle.

The combined mass and volume of the two resulting particles are the same as those of the split particle.

Parameters:
  • childDirection (FVector3) – direction along which the particle is split.

  • childRatio (float) – ratio of the child particle volume to the split particle volume. Must be in (0, 1).

  • parentType (ParticleType, optional) – optional type of the split particle after the split

  • childType (ParticleType, optional) – optional type of the new particle

Return type:

ParticleHandle

Returns:

new particle


Overload 6:

Splits a single particle into two along a given direction, with sizes according to a given ratio, allocates species according to given ratios, and optionally with different resulting particle types.

The new particle is placed along the orientation of the passed direction.

The new particle has a mass and volume equal to those of the split particle multiplied by a ratio.

If species are attached to the split particle, then the amount of species is allocated to the two resulting particles such that the total amount in the new particles is equal to the total amount of the split particle multiplied by a ratio. Species are conserved.

The two resulting particles have the type of the split particle unless otherwise specified.

The two resulting particles are placed in contact.

The center of mass of the two resulting particles is the same as that of the split particle.

The combined mass and volume of the two resulting particles are the same as those of the split particle.

Parameters:
  • childDirection (FVector3) – direction along which the particle is split.

  • childRatio (float) – ratio of the child particle volume to the split particle volume. Must be in (0, 1).

  • speciesRatios (std::vector< FPTYPE,std::allocator< FPTYPE > >) – ratio of the child particle total species amount to the split particle total species amount. Each must be in (0, 1).

  • parentType (ParticleType, optional) – optional type of the split particle after the split

  • childType (ParticleType, optional) – optional type of the new particle

Return type:

ParticleHandle

Returns:

new particle

destroy()

Destroys the particle and removes it from inventory.

Subsequent references to a destroyed particle result in an error.

sphericalPosition(particle=None, origin=None)

Calculates the particle’s coordinates in spherical coordinates.

By default, calculations are made with respect to the center of the universe.

Parameters:
  • particle (Particle, optional) – a particle to use as the origin, optional

  • origin (FVector3, optional) – a point to use as the origin, optional

virial(radius=None)

Computes the virial tensor. Optionally pass a distance to include a neighborhood.

Parameters:

radius (float, optional) – A distance to define a neighborhood, optional

become(type)

Dynamically changes the type of an object. We can change the type of a ParticleType-derived object to anyther pre-existing ParticleType-derived type. What this means is that if we have an object of say type A, we can change it to another type, say B, and and all of the forces and processes that acted on objects of type A stip and the forces and processes defined for type B now take over.

Parameters:

type (ParticleType) – new particle type

neighbors(distance=None, types=None)

Gets a list of nearby particles.

Parameters:
  • distance – optional search distance; default is simulation cutoff

  • types – optional list of particle types to search by; default is all types

Return type:

ParticleList

bonded_neighbors()

All bonded neighbor ids.

distance(_other)

Calculates the distance to another particle

Parameters:

_other (ParticleHandle) – another particle.

to_cluster()

Limits casting to cluster by type

__str__() str

Return str(self).

__lt__(rhs) bool

Return self<value.

__gt__(rhs) bool

Return self>value.

__le__(rhs) bool

Return self<=value.

__ge__(rhs) bool

Return self>=value.

__eq__(rhs) bool

Return self==value.

__ne__(rhs) bool

Return self!=value.

class tissue_forge.ParticleTypeSpec

Interface for class-centric design of ParticleType

mass = None

Particle type mass

charge = None

Particle type charge

radius = None

Particle type radius

target_energy = None

Particle type target energy

minimum_radius = None

Particle type minimum radius

eps = None

Particle type nonbonded interaction parameter

rmin = None

Particle type nonbonded interaction parameter

dynamics = None

Particle type dynamics flag

frozen = None

Particle type frozen flag

name = None

Particle type name

name2 = None

Particle type second name

style = None

Particle type style dictionary specification.

Basic rendering details can be specified as a dictionary, like color and visibility,

style = {'color': 'CornflowerBlue', 'visible': False}

This declaration is the same as performing operations on a type after registration,

ptype: ParticleType
ptype.style.setColor('CornflowerBlue')
ptype.style.setVisible(False)

Rendering instead by species and species amount uses specification for a color mapper,

style = {'colormap': {'species': 'S1', 'map': 'rainbow', 'range': (0, 10)}}

This declaration is the same as performing operations on a type after registration,

ptype: ParticleType
ptype.style.mapper = rendering.ColorMapper('rainbow', 0, 10)
ptype.style.mapper.set_map_particle_species(ptype, 'S1')

Valid entries for data mapping are as follows,

  • ‘force’: ‘x’, ‘y’ or ‘z’ for x-, y- or z-component of force

  • ‘position’: ‘x’, ‘y’ or ‘z’ for x-, y- or z-component of position

  • ‘species’: Name of a species attached to a particle type

  • ‘velocity’: ‘x’, ‘y’, ‘z’ or ‘speed’ for x-, y-, z-component or magnitude of velocity

species = None

Particle type list of species by name, if any. Species are automatically created and populated in the state vector of the type and all created particles.

classmethod get()

Get the engine type that corresponds to this class.

The type is automatically registered as necessary.

Returns:

registered type instance

Return type:

tissue_forge.ParticleType

class tissue_forge.ParticleType(noReg=False)

Structure containing information on each particle type.

This is only a definition for a type of particle, and not an actual particle with position, velocity, etc. However, particles of this type can be created with one of these.

property frozen

Particle type frozen flag

property frozen_x

Particle type frozen flag along x

property frozen_y

Particle type frozen flag along y

property frozen_z

Particle type frozen flag along z

property temperature

Particle type temperature

property target_temperature

Particle type target temperature

id

ID of this type

mass

Default mass of particles

charge

Default charge of particles

radius

Default radius of particles

property volume

Particle type volume

kinetic_energy

Kinetic energy of all particles of this type.

potential_energy

Potential energy of all particles of this type.

target_energy

Target energy of all particles of this type.

minimum_radius

Default minimum radius of this type.

If a split event occurs, resulting particles will have a radius at least as great as this value.

dynamics

Default dynamics of particles of this type.

name

Name of this particle type.

style

style pointer, optional.

species

optional pointer to species list. This is the metadata for the species

parts

list of particles that belong to this type.

particle(i)

get the i’th particle that’s a member of this type.

Parameters:

i (int) – index of particle to get

static particleTypeIds()

Get all current particle type ids, excluding clusters

__str__()

Return str(self).

__getitem__(index: int)
__contains__(item)
__lt__(rhs) bool

Return self<value.

__gt__(rhs) bool

Return self>value.

__le__(rhs) bool

Return self<=value.

__ge__(rhs) bool

Return self>=value.

__eq__(rhs) bool

Return self==value.

__ne__(rhs) bool

Return self!=value.

__call__(*args, **kwargs)

Call self as a function.

Alias of _call

_call(*args)

Overload 1:

Particle constructor.

Automatically updates when running on a CUDA device.

Parameters:
  • position (FVector3, optional) – position of new particle, optional

  • velocity (FVector3, optional) – velocity of new particle, optional

  • clusterId (int, optional) – id of parent cluster, optional

Return type:

ParticleHandle

Returns:

new particle


Overload 2:

Particle constructor.

Automatically updates when running on a CUDA device.

Parameters:
  • str (string) – JSON string

  • clusterId (int, optional) – id of parent cluster, optional

Return type:

ParticleHandle

Returns:

new particle

factory(nr_parts=0, positions=None, velocities=None, cluster_ids=None)

Particle factory constructor, for making lots of particles quickly.

At minimum, arguments must specify the number of particles to create, whether specified explicitly or through one or more vector arguments.

Parameters:
  • nr_parts – number of particles to create, optional

  • positions – initial particle positions, optional

  • velocities – initial particle velocities, optional

  • clusterIds – parent cluster ids, optional

Returns:

ids of created particles

newType(_name)

Particle type constructor.

New type is constructed from the definition of the calling type.

Parameters:

_name (string) – name of the new type

Return type:

ParticleType

Returns:

new particle type

registerType()

Registers a type with the engine.

Note that this occurs automatically, unless noReg==true in constructor.

on_register()

A callback for when a type is registered

isRegistered()

Tests whether this type is registered

Return type:

boolean

Returns:

true if registered

get()

Get the type engine instance

items()

Get all particles of this type.

isCluster()

Test whether the type is a cluster type

to_cluster()

Limits casting to cluster by type

toString()

Get a JSON string representation

static fromString(str)

Create from a JSON string representation.

The returned type is automatically registered with the engine.

Parameters:

str (string) – a string, as returned by toString

__reduce__()

Helper for pickle.

class tissue_forge.Cluster

Bases: Particle

The cluster analogue to Particle.

class tissue_forge.ClusterParticleHandle(*args)

Bases: ParticleHandle

The cluster analogue to ParticleHandle.

These are special in that they can create particles of their constituent particle types, much like a ParticleType.

property radius_of_gyration

Radius of gyration

property center_of_mass

Center of mass

property centroid

Centroid

property moment_of_inertia

Moment of inertia

property num_parts

number of particles that belong to this cluster.

property parts

particles that belong to this cluster.

items = <function ClusterParticleHandle.items>
has(*args)

Overload 1: Test whether the cluster has an id


Overload 2: Test whether the cluster has a particle

__str__()

Return str(self).

__getitem__(index: int)
__contains__(item)
__lt__(rhs) bool

Return self<value.

__gt__(rhs) bool

Return self>value.

__le__(rhs) bool

Return self<=value.

__ge__(rhs) bool

Return self>=value.

__eq__(rhs) bool

Return self==value.

__ne__(rhs) bool

Return self!=value.

__call__(particle_type, *args, **kwargs)

Call self as a function.

Alias of _call

_call(*args)

Overload 1:

Constituent particle constructor.

The created particle will belong to this cluster.

Automatically updates when running on a CUDA device.

Parameters:
  • partType (ParticleType) – type of particle to create

  • position (FVector3, optional) – position of new particle, optional

  • velocity (FVector3, optional) – velocity of new particle, optional

Return type:

ParticleHandle

Returns:

ParticleHandle*


Overload 2:

Constituent particle constructor.

The created particle will belong to this cluster.

Automatically updates when running on a CUDA device.

Parameters:
  • partType (ParticleType) – type of particle to create

  • str (string) – JSON string

Return type:

ParticleHandle

Returns:

ParticleHandle*

cluster()

Gets the actual cluster of this handle.

Return type:

Cluster

Returns:

Particle*

split(axis=None, random=None, time=None, normal=None, point=None)

Split the cluster.

Parameters:
  • axis (FVector3, optional) – axis of split, optional

  • random (boolean, optional) – divide by randomly and evenly allocating constituent particles, optional

  • time (float, optional) – time at which to implement the split; currently not supported

  • normal (FVector3, optional) – normal vector of cleavage plane, optional

  • point (FVector3, optional) – point on cleavage plane, optional

Return type:

ParticleHandle

Returns:

ParticleHandle*

class tissue_forge.ClusterTypeSpec

Bases: ParticleTypeSpec

Interface for class-centric design of ClusterParticleType

types = None

List of constituent types of the cluster, if any

class tissue_forge.ClusterParticleType(noReg=False)

Bases: ParticleType

The cluster analogue to ParticleType.

types

list of particle types that belong to this type.

hasType(type)

Tests where this cluster has a particle type.

Only tests for immediate ownership and ignores multi-level clusters.

Parameters:

type (ParticleType) – type to test

Return type:

boolean

Returns:

true if this cluster has the type

get()

Get the type engine instance

Return type:

ClusterParticleType

Returns:

ClusterParticleType*

has(*args)

Overload 1: Test whether the type has a type id


Overload 2: Test whether the type has a type


Overload 3: Test whether the type has a particle

__str__()

Return str(self).

__getitem__(index: int)
__contains__(item)
__lt__(rhs) bool

Return self<value.

__gt__(rhs) bool

Return self>value.

__le__(rhs) bool

Return self<=value.

__ge__(rhs) bool

Return self>=value.

__eq__(rhs) bool

Return self==value.

__ne__(rhs) bool

Return self!=value.

ParticleList and ParticleTypeList

class tissue_forge.ParticleList(*args)

A special list with convenience methods for working with sets of particles.

property virial

Virial tensor of particles in list

property radius_of_gyration

Radius of gyration of particles in list

property center_of_mass

Center of mass of particles in list

property centroid

Centroid of particles in list

property moment_of_inertia

Moment of inertia of particles in list

property positions

Position of each particle in list

property velocities

Velocity of each particle in list

property forces

Net forces acting on each particle in list

property ownsdata: bool

Whether the list owns its data

property mutable: bool

Whether the list is mutable

has(*args)

Overload 1: Test whether the list has an id


Overload 2: Test whether the list has a particle

__len__() int
__getitem__(i: int)
__contains__(item)
reserve(_nr_parts)

Reserve enough storage for a given number of items.

Parameters:

_nr_parts (int) – number of items

Return type:

int

Returns:

HRESULT

insert(*args)

Inserts the given particle into the list, returns the index of the item.

Parameters:

particle (ParticleHandle) – particle to insert

Return type:

int

Returns:

uint16_t

remove(id)

looks for the item with the given id and deletes it form the list

Parameters:

id (int) – id to remove

Return type:

int

Returns:

uint16_t

extend(other)

inserts the contents of another list

Parameters:

other (ParticleList) – another list

item(i)

looks for the item at the given index and returns it if found, otherwise returns NULL

Parameters:

i (int) – index of lookup

Return type:

ParticleHandle

Returns:

ParticleHandle*

vector()

returns the list as a vector

static all()

returns an instance populated with all current particles

Return type:

ParticleList

Returns:

ParticleList*

sphericalPositions(origin=None)

Get the spherical coordinates of each particle

Parameters:

origin (FVector3, optional) – optional origin of coordinates; default is center of universe

Return type:

std::vector< TissueForge::FVector3,std::allocator< TissueForge::FVector3 > >

Returns:

std::vector<FVector3>

toString()

Get a JSON string representation

Return type:

string

Returns:

std::string

static fromString(str)

Create from a JSON string representation

Parameters:

str (string) –

Return type:

ParticleList

Returns:

ParticleList*

__reduce__()

Helper for pickle.

class tissue_forge.ParticleTypeList(*args)

A special list with convenience methods for working with sets of particle types.

property virial

Virial tensor of particles corresponding to all types in list

property radius_of_gyration

Radius of gyration of particles corresponding to all types in list

property center_of_mass

Center of mass of particles corresponding to all types in list

property centroid

Centroid of particles corresponding to all types in list

property moment_of_inertia

Moment of inertia of particles corresponding to all types in list

property positions

Position of each particle corresponding to all types in list

property velocities

Velocity of each particle corresponding to all types in list

property forces

Total net force acting on each particle corresponding to all types in list

property ownsdata: bool

Whether the list owns its data

property mutable: bool

Whether the list is mutable

has(*args)

Overload 1: Test whether the list has an id


Overload 2: Test whether the list has a particle type


Overload 3: Test whether the list has a particle

__len__() int
__getitem__(i: int)
__contains__(item)
reserve(_nr_parts)

Reserve enough storage for a given number of items.

Parameters:

_nr_parts (int) – number of items

Return type:

int

Returns:

HRESULT

insert(*args)

Inserts the given particle type into the list, returns the index of the item.

Parameters:

ptype (ParticleType) –

Return type:

int

Returns:

uint16_t

remove(id)

looks for the item with the given id and deletes it form the list

Parameters:

id (int) – id to remove

Return type:

int

Returns:

uint16_t

extend(other)

inserts the contents of another list

Parameters:

other (ParticleTypeList) – another list

item(i)

looks for the item at the given index and returns it if found, otherwise returns NULL

Parameters:

i (int) – index of lookup

Return type:

ParticleType

Returns:

ParticleType*

vector()

returns the list as a vector

static all()

returns an instance populated with all current particle types

Return type:

ParticleTypeList

Returns:

ParticleTypeList*

sphericalPositions(origin=None)

Get the spherical coordinates of each particle

Parameters:

origin (FVector3, optional) – optional origin of coordinates; default is center of universe

Return type:

std::vector< TissueForge::FVector3,std::allocator< TissueForge::FVector3 > >

Returns:

std::vector<FVector3>

toString()

Get a JSON string representation

Return type:

string

Returns:

std::string

static fromString(str)

Create from a JSON string representation

Parameters:

str (string) –

Return type:

ParticleTypeList

Returns:

ParticleTypeList*

__reduce__()

Helper for pickle.

Potentials

class tissue_forge.tissue_forge._Potential

A Potential object is a compiled interpolation of a given function. The Universe applies potentials to particles to calculate the net force on them.

For performance reasons, Tissue Forge implements potentials as interpolations, which can be much faster than evaluating the function directly.

A potential can be treated just like any callable object.

property min: float

Minimum distance of evaluation

property max: float

Maximum distance of evaluation

property cutoff: float

Cutoff distance

property domain: (<class 'float'>, <class 'float'>)

Evaluation domain

property intervals: int

Evaluation intervals

property bound: bool

Bound flag

property r0: float

Potential r0 value

property shifted: bool

Shifted flag

property periodic: bool

Periodic flag

property r_square: bool

Potential r2 value

__call__()

Alias of _call

_call(*args)
plot(s=1.0, force=True, potential=False, show=True, ymin=None, ymax=None, *args, **kwargs)

Potential plot function

Parameters:
  • s – sum of theoretical radii of two interacting particles

  • force – flag to plot evaluations of the force magnitude

  • potential – flag to plot evaluations of the potential

  • show – flag to show the plot

  • ymin – minimum vertical plot value

  • ymax – maximum vertical plot value

Returns:

plot lines

toString()

Get a JSON string representation

Return type:

string

Returns:

std::string

static fromString(str)

Create from a JSON string representation

Parameters:

str (string) –

Return type:

Potential

Returns:

Potential*

__reduce__()

Helper for pickle.

static lennard_jones_12_6(min, max, A, B, tol=None)

Creates a 12-6 Lennard-Jones potential.

The Lennard Jones potential has the form:

\[\left( \frac{A}{r^{12}} - \frac{B}{r^6} \right)\]
Parameters:
  • min (float) – The smallest radius for which the potential will be constructed.

  • max (float) – The largest radius for which the potential will be constructed.

  • A (float) – The first parameter of the Lennard-Jones potential.

  • B (float) – The second parameter of the Lennard-Jones potential.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001 * (max - min).

Return type:

Potential

Returns:

Potential*

static lennard_jones_12_6_coulomb(min, max, A, B, q, tol=None)

Creates a potential of the sum of a 12-6 Lennard-Jones potential and a shifted Coulomb potential.

The 12-6 Lennard Jones - Coulomb potential has the form:

\[\left( \frac{A}{r^{12}} - \frac{B}{r^6} \right) + q \left( \frac{1}{r} - \frac{1}{max} \right)\]
Parameters:
  • min (float) – The smallest radius for which the potential will be constructed.

  • max (float) – The largest radius for which the potential will be constructed.

  • A (float) – The first parameter of the Lennard-Jones potential.

  • B (float) – The second parameter of the Lennard-Jones potential.

  • q (float) – The charge scaling of the potential.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001 * (max - min).

Return type:

Potential

Returns:

Potential*

static ewald(min, max, q, kappa, tol=None, periodicOrder=None)

Creates a real-space Ewald potential.

The Ewald potential has the form:

\[q \frac{\mathrm{erfc}\, ( \kappa r)}{r}\]
Parameters:
  • min (float) – The smallest radius for which the potential will be constructed.

  • max (float) – The largest radius for which the potential will be constructed.

  • q (float) – The charge scaling of the potential.

  • kappa (float) – The screening distance of the Ewald potential.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001 * (max - min).

  • periodicOrder (int, optional) – Order of lattice periodicity along all periodic dimensions. Defaults to 0.

Return type:

Potential

Returns:

Potential*

static coulomb(q, min=None, max=None, tol=None, periodicOrder=None)

Creates a Coulomb potential.

The Coulomb potential has the form:

\[\frac{q}{r}\]
Parameters:
  • q (float) – The charge scaling of the potential.

  • min (float, optional) – The smallest radius for which the potential will be constructed. Default is 0.01.

  • max (float, optional) – The largest radius for which the potential will be constructed. Default is 2.0.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001 * (max - min).

  • periodicOrder (int, optional) – Order of lattice periodicity along all periodic dimensions. Defaults to 0.

Return type:

Potential

Returns:

Potential*

static coulombR(q, kappa, min, max, modes=None)

Creates a Coulomb reciprocal potential.

The Coulomb reciprocal potential has the form:

\[\frac{\pi q}{V} \sum_{||\mathbf{m}|| \neq 0} \frac{1}{||\mathbf{m}||^2} \exp \left( \left( i \mathbf{r}_{jk} - \left( \frac{\pi}{\kappa} \right)^{2} \mathbf{m} \right) \cdot \mathbf{m} \right)\]

Here \(V\) is the volume of the domain and \(\mathbf{m}\) is a reciprocal vector of the domain.

Parameters:
  • q (float) – Charge scaling of the potential.

  • kappa (float) – Screening distance.

  • min (float) – Smallest radius for which the potential will be constructed.

  • max (float) – Largest radius for which the potential will be constructed.

  • modes (int, optional) – Number of Fourier modes along each periodic dimension. Default is 1.

Return type:

Potential

Returns:

Potential*

static harmonic(k, r0, min=None, max=None, tol=None)

Creates a harmonic bond potential.

The harmonic potential has the form:

\[k \left( r-r_0 \right)^2\]
Parameters:
  • k (float) – The energy of the bond.

  • r0 (float) – The bond rest length.

  • min (float, optional) – The smallest radius for which the potential will be constructed. Defaults to \(r_0 - r_0 / 2\).

  • max (float, optional) – The largest radius for which the potential will be constructed. Defaults to \(r_0 + r_0 /2\).

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to \(0.01 \abs(max-min)\).

Return type:

Potential

Returns:

Potential*

static linear(k, min=None, max=None, tol=None)

Creates a linear potential.

The linear potential has the form:

\[k r\]
Parameters:
  • k (float) – interaction strength; represents the potential energy peak value.

  • min (float, optional) – The smallest radius for which the potential will be constructed. Defaults to 0.0.

  • max (float, optional) – The largest radius for which the potential will be constructed. Defaults to 10.0.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001.

Return type:

Potential

Returns:

Potential*

static harmonic_angle(k, theta0, min=None, max=None, tol=None)

Creates a harmonic angle potential.

The harmonic angle potential has the form:

\[k \left(\theta-\theta_{0} \right)^2\]
Parameters:
  • k (float) – The energy of the angle.

  • theta0 (float) – The minimum energy angle.

  • min (float, optional) – The smallest angle for which the potential will be constructed. Defaults to zero.

  • max (float, optional) – The largest angle for which the potential will be constructed. Defaults to PI.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.005 * (max - min).

Return type:

Potential

Returns:

Potential*

static harmonic_dihedral(k, delta, min=None, max=None, tol=None)

Creates a harmonic dihedral potential.

The harmonic dihedral potential has the form:

\[k \left( \theta - \delta \right) ^2\]
Parameters:
  • k (float) – energy of the dihedral.

  • delta (float) – minimum energy dihedral.

  • min (float, optional) – The smallest angle for which the potential will be constructed. Defaults to zero.

  • max (float, optional) – The largest angle for which the potential will be constructed. Defaults to PI.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.005 * (max - min).

Return type:

Potential

Returns:

Potential*

static cosine_dihedral(k, n, delta, tol=None)

Creates a cosine dihedral potential.

The cosine dihedral potential has the form:

\[k \left( 1 + \cos( n \theta-\delta ) \right)\]
Parameters:
  • k (float) – energy of the dihedral.

  • n (int) – multiplicity of the dihedral.

  • delta (float) – minimum energy dihedral.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.01.

Return type:

Potential

Returns:

Potential*

static well(k, n, r0, min=None, max=None, tol=None)

Creates a well potential.

Useful for binding a particle to a region.

The well potential has the form:

\[\frac{k}{\left(r_0 - r\right)^{n}}\]
Parameters:
  • k (float) – potential prefactor constant, should be decreased for larger n.

  • n (float) – exponent of the potential, larger n makes a sharper potential.

  • r0 (float) – The extents of the potential, length units. Represents the maximum extents that a two objects connected with this potential should come apart.

  • min (float, optional) – The smallest radius for which the potential will be constructed. Defaults to zero.

  • max (float, optional) – The largest radius for which the potential will be constructed. Defaults to r0.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.01 * abs(min-max).

Return type:

Potential

Returns:

Potential*

static glj(e, m=None, n=None, k=None, r0=None, min=None, max=None, tol=None, shifted=None)

Creates a generalized Lennard-Jones potential.

The generalized Lennard-Jones potential has the form:

\[\frac{\epsilon}{n-m} \left[ m \left( \frac{r_0}{r} \right)^n - n \left( \frac{r_0}{r} \right)^m \right]\]
Parameters:
  • e (float) – effective energy of the potential.

  • m (float, optional) – order of potential. Defaults to 3

  • n (float, optional) – order of potential. Defaults to 2*m.

  • k (float, optional) – mimumum of the potential. Defaults to 1.

  • r0 (float, optional) – mimumum of the potential. Defaults to 1.

  • min (float, optional) – The smallest radius for which the potential will be constructed. Defaults to 0.05 * r0.

  • max (float, optional) – The largest radius for which the potential will be constructed. Defaults to 5 * r0.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.01.

  • shifted (boolean, optional) – Flag for whether using a shifted potential. Defaults to true.

Return type:

Potential

Returns:

Potential*

static morse(d=None, a=None, r0=None, min=None, max=None, tol=None, shifted=None)

Creates a Morse potential.

The Morse potential has the form:

\[d \left(1 - e^{ -a \left(r - r_0 \right) } \right)^2\]
Parameters:
  • d (float, optional) – well depth. Defaults to 1.0.

  • a (float, optional) – potential width. Defaults to 6.0.

  • r0 (float, optional) – equilibrium distance. Defaults to 0.0.

  • min (float, optional) – The smallest radius for which the potential will be constructed. Defaults to 0.0001.

  • max (float, optional) – The largest radius for which the potential will be constructed. Defaults to 3.0.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001.

  • shifted (boolean, optional) – Flag for whether using a shifted potential. Defaults to true.

Return type:

Potential

Returns:

Potential*

static overlapping_sphere(mu=None, kc=None, kh=None, r0=None, min=None, max=None, tol=None)

Creates an overlapping-sphere potential from [OFPF+17].

The overlapping-sphere potential has the form:

\[\mu_{ij} s_{ij}(t) \hat{\mathbf{r}}_{ij} \log \left( 1 + \frac{||\mathbf{r}_{ij}|| - s_{ij}(t)}{s_{ij}(t)} \right) \text{ if } ||\mathbf{r}_{ij}|| < s_{ij}(t) ,\]
\[\mu_{ij}\left(||\mathbf{r}_{ij}|| - s_{ij}(t)\right) \hat{\mathbf{r}}_{ij} \exp \left( -k_c \frac{||\mathbf{r}_{ij}|| - s_{ij}(t)}{s_{ij}(t)} \right) \text{ if } s_{ij}(t) \leq ||\mathbf{r}_{ij}|| \leq r_{max} ,\]
\[0 \text{ otherwise} .\]

Osborne refers to \(\mu_{ij}\) as a “spring constant”, this controls the size of the force, and is the potential energy peak value. \(\hat{\mathbf{r}}_{ij}\) is the unit vector from particle \(i\) center to particle \(j\) center, \(k_C\) is a parameter that defines decay of the attractive force. Larger values of \(k_C\) result in a shaper peaked attraction, and thus a shorter ranged force. \(s_{ij}(t)\) is the is the sum of the radii of the two particles.

Parameters:
  • mu (float, optional) – interaction strength, represents the potential energy peak value. Defaults to 1.0.

  • kc (float, optional) – decay strength of long range attraction. Larger values make a shorter ranged function. Defaults to 1.0.

  • kh (float, optional) – Optionally add a harmonic long-range attraction, same as glj function. Defaults to 0.0.

  • r0 (float, optional) – Optional harmonic rest length, only used if kh is non-zero. Defaults to 0.0.

  • min (float, optional) – The smallest radius for which the potential will be constructed. Defaults to 0.001.

  • max (float, optional) – The largest radius for which the potential will be constructed. Defaults to 10.0.

  • tol (float, optional) – The tolerance to which the interpolation should match the exact potential. Defaults to 0.001.

Return type:

Potential

Returns:

Potential*

static power(k=None, r0=None, alpha=None, min=None, max=None, tol=None)

Creates a power potential.

The power potential the general form of many of the potential functions, such as linear, etc. power has the form:

\[k \lvert r-r_0 \rvert ^{\alpha}\]
Parameters:
  • k (float, optional) – interaction strength, represents the potential energy peak value. Defaults to 1

  • r0 (float, optional) – potential rest length, zero of the potential, defaults to 0.

  • alpha (float, optional) – Exponent, defaults to 1.

  • min (float, optional) – minimal value potential is computed for, defaults to r0 / 2.

  • max (float, optional) – cutoff distance, defaults to 3 * r0.

  • tol (float, optional) – Tolerance, defaults to 0.01.

Return type:

Potential

Returns:

Potential*

static dpd(alpha=None, gamma=None, sigma=None, cutoff=None, shifted=None)

Creates a Dissipative Particle Dynamics potential.

The Dissipative Particle Dynamics force has the form:

\[\mathbf{F}_{ij} = \mathbf{F}^C_{ij} + \mathbf{F}^D_{ij} + \mathbf{F}^R_{ij}\]

The conservative force is:

\[\mathbf{F}^C_{ij} = \alpha \left(1 - \frac{r_{ij}}{r_c}\right) \mathbf{e}_{ij}\]

The dissapative force is:

\[\mathbf{F}^D_{ij} = -\gamma \left(1 - \frac{r_{ij}}{r_c}\right)^{2}(\mathbf{e}_{ij} \cdot \mathbf{v}_{ij}) \mathbf{e}_{ij}\]

The random force is:

\[\mathbf{F}^R_{ij} = \sigma \left(1 - \frac{r_{ij}}{r_c}\right) \xi_{ij}\Delta t^{-1/2}\mathbf{e}_{ij}\]
Parameters:
  • alpha (float, optional) – interaction strength of the conservative force. Defaults to 1.0.

  • gamma (float, optional) – interaction strength of dissapative force. Defaults to 1.0.

  • sigma (float, optional) – strength of random force. Defaults to 1.0.

  • cutoff (float, optional) – cutoff distance. Defaults to 1.0.

  • shifted (boolean, optional) – Flag for whether using a shifted potential. Defaults to false.

Return type:

Potential

Returns:

Potential*

class tissue_forge.tissue_forge.Potential

Bases: _Potential

custom = <function Potential.custom>
class tissue_forge.tissue_forge.DPDPotential(alpha, gamma, sigma, cutoff, shifted)

Bases: _Potential

alpha

strength of conserative interaction

gamma

strength of dissapative interaction

sigma

strength of random interaction

static fromPot(pot)

Convert basic potential to DPD.

If the basic potential is not DPD, then NULL is returned.

Parameters:

pot (Potential) –

Return type:

DPDPotential

Returns:

DPDPotential*

toString()

Get a JSON string representation

Return type:

string

Returns:

std::string

static fromString(str)

Create from a JSON string representation

Parameters:

str (string) –

Return type:

DPDPotential

Returns:

Potential*

__reduce__()

Helper for pickle.

Forces

class tissue_forge.tissue_forge.Force

Force is a metatype, in that Tissue Forge has lots of different instances of force functions, that have different attributes, but only have one base type.

Forces are one of the fundamental processes in Tissue Forge that cause objects to move.

bind_species(a_type, coupling_symbol)

Bind a force to a species.

When a force is bound to a species, the magnitude of the force is scaled by the concentration of the species.

Parameters:
  • a_type (ParticleType) – particle type containing the species

  • coupling_symbol (string) – symbol of the species

Return type:

int

Returns:

HRESULT

static berendsen_tstat(tau)

Creates a Berendsen thermostat.

The thermostat uses the target temperature \(T_0\) from the object to which it is bound. The Berendsen thermostat effectively re-scales the velocities of an object in order to make the temperature of that family of objects match a specified temperature.

The Berendsen thermostat force has the function form:

\[\frac{\mathbf{p}}{\tau_T} \left(\frac{T_0}{T} - 1 \right),\]

where \(\mathbf{p}\) is the momentum, \(T\) is the measured temperature of a family of particles, \(T_0\) is the control temperature, and \(\tau_T\) is the coupling constant. The coupling constant is a measure of the time scale on which the thermostat operates, and has units of time. Smaller values of \(\tau_T\) result in a faster acting thermostat, and larger values result in a slower acting thermostat.

Parameters:

tau (float) – time constant that determines how rapidly the thermostat effects the system.

Return type:

Berendsen

Returns:

Berendsen*

static random(std, mean, duration=0.01)

Creates a random force.

A random force has a randomly selected orientation and magnitude.

Orientation is selected according to a uniform distribution on the unit sphere.

Magnitude is selected according to a prescribed mean and standard deviation.

Parameters:
  • std (float) – standard deviation of magnitude

  • mean (float) – mean of magnitude

  • duration (float, optional) – duration of force. Defaults to 0.01.

Return type:

Gaussian

Returns:

Gaussian*

static friction(coef)

Creates a friction force.

A friction force has the form:

\[- \frac{|| \mathbf{v} ||}{\tau} \mathbf{v} ,\]

where \(\mathbf{v}\) is the velocity of a particle and \(\tau\) is a time constant.

Parameters:

coef (float) – time constant

Return type:

Friction

Returns:

Friction*

toString()

Get a JSON string representation

Return type:

string

Returns:

std::string

static fromString(str)

Create from a JSON string representation

Parameters:

str (string) –

Return type:

Force

Returns:

Force*

__reduce__()

Helper for pickle.

class tissue_forge.tissue_forge._CustomForce(*args)

Bases: Force

A custom force function.

The force is updated according to an update frequency.

static fromForce(f)

Convert basic force to CustomForce.

If the basic force is not a CustomForce, then NULL is returned.

Parameters:

f (Force) –

Return type:

CustomForce

Returns:

CustomForce*

class tissue_forge.tissue_forge.CustomForce(*args)

Bases: _CustomForce

Creates an instance from an underlying custom python function

Parameters:
  • f (PyObject) – python function. Takes no arguments and returns a three-component vector.

  • period (float, optional) – period at which the force is updated.

property value

Current value of the force.

This can be set to a function that takes no arguments and returns a 3-component list of floats.

property period

Period of the force

static fromForce(f)

Convert basic force to CustomForcePy.

If the basic force is not a CustomForcePy, then NULL is returned.

Parameters:

f (Force) –

Return type:

CustomForcePy

Returns:

CustomForcePy*

class tissue_forge.tissue_forge.ForceSum

Bases: Force

f1
f2
static fromForce(f)

Convert basic force to force sum.

If the basic force is not a force sum, then NULL is returned.

Parameters:

f (Force) –

Return type:

ForceSum

Returns:

ForceSum*

class tissue_forge.tissue_forge.Berendsen

Bases: Force

Berendsen force.

Create one with Force.berendsen_tstat.

itau

time constant

static fromForce(f)

Convert basic force to Berendsen.

If the basic force is not a Berendsen, then NULL is returned.

Parameters:

f (Force) –

Return type:

Berendsen

Returns:

Berendsen*

class tissue_forge.tissue_forge.Gaussian

Bases: Force

Random force.

Create one with Force.random.

std

standard deviation of magnitude

mean

mean of magnitude

durration_steps

duration of force.

static fromForce(f)

Convert basic force to Gaussian.

If the basic force is not a Gaussian, then NULL is returned.

Parameters:

f (Force) –

Return type:

Gaussian

Returns:

Gaussian*

class tissue_forge.tissue_forge.Friction

Bases: Force

Friction force.

Create one with Force.friction.

coef

time constant

static fromForce(f)

Convert basic force to Friction.

If the basic force is not a Friction, then NULL is returned.

Parameters:

f (Force) –

Return type:

Friction

Returns:

Friction*

Fluxes

class tissue_forge.Fluxes

A flux is defined between a pair of types, and acts on the state vector between a pair of instances.

The indices of the species in each state vector are most likely different, so Tissue Forge tracks the indices in each type, and the transport constatants.

A flux between a pair of types, and pair of respective species needs:

(1) type A, (2) type B, (3) species id in A, (4) species id in B, (5) transport constant.

Allocates Flux as a single block, member pointers point to offsets in these blocks.

Allocated size is: sizeof(Fluxes) + 2 * alloc_size * sizeof(int32) + alloc_size * sizeof(FPTYPE)

static flux(*args, **kwargs)

Alias of fluxFick.

Parameters:
  • A (ParticleType) – first type

  • B (ParticleType) – second type

  • name (string) – name of species

  • k (float) – transport coefficient

  • decay (float, optional) – optional decay. Defaults to 0.0.

  • cutoff (float, optional) – optional cutoff distance. Defaults to global cutoff

Return type:

Fluxes

Returns:

Fluxes*

static fluxFick(*args, **kwargs)

Creates and binds a Fickian diffusion flux.

Fickian diffusion flux implements the analogous reaction:

\[a.S \leftrightarrow b.S ; k \left(1 - \frac{r}{r_{cutoff}} \right)\left(a.S - b.S\right) ,\]
\[a.S \rightarrow 0 ; \frac{d}{2} a.S ,\]
\[b.S \rightarrow 0 ; \frac{d}{2} b.S ,\]

where \(a.S\) is a chemical species located at object \(a\), and likewise for \(b\), \(k\) is the flux constant, \(r\) is the distance between the two objects, \(r_{cutoff}\) is the global cutoff distance, and \(d\) is an optional decay term.

Automatically updates when running on a CUDA device.

Parameters:
  • A (ParticleType) – first type

  • B (ParticleType) – second type

  • name (string) – name of species

  • k (float) – transport coefficient

  • decay (float, optional) – optional decay. Defaults to 0.0.

  • cutoff (float, optional) – optional cutoff distance. Defaults to global cutoff

Return type:

Fluxes

Returns:

Fluxes*

static secrete(*args, **kwargs)

Creates a secretion flux by active pumping.

Secretion flux implements the analogous reaction:

\[a.S \rightarrow b.S ; k \left(1 - \frac{r}{r_{cutoff}} \right)\left(a.S - a.S_{target} \right) ,\]
\[a.S \rightarrow 0 ; \frac{d}{2} a.S ,\]
\[b.S \rightarrow 0 ; \frac{d}{2} b.S ,\]

where \(a.S\) is a chemical species located at object \(a\), and likewise for \(b\), \(k\) is the flux constant, \(r\) is the distance between the two objects, \(r_{cutoff}\) is the global cutoff distance, and \(d\) is an optional decay term.

Automatically updates when running on a CUDA device.

Parameters:
  • A (ParticleType) – first type

  • B (ParticleType) – second type

  • name (string) – name of species

  • k (float) – transport coefficient

  • target (float) – target concentration

  • decay (float, optional) – optional decay. Defaults to 0.0

  • cutoff (float, optional) – optional cutoff distance. Defaults to global cutoff

Return type:

Fluxes

Returns:

Fluxes*

static uptake(*args, **kwargs)

Creates an uptake flux by active pumping.

Uptake flux implements the analogous reaction:

\[a.S \rightarrow b.S ; k \left(1 - \frac{r}{r_{cutoff}}\right)\left(b.S - b.S_{target} \right)\left(a.S\right) ,\]
\[a.S \rightarrow 0 ; \frac{d}{2} a.S ,\]
\[b.S \rightarrow 0 ; \frac{d}{2} b.S ,\]

where \(a.S\) is a chemical species located at object \(a\), and likewise for \(b\), \(k\) is the flux constant, \(r\) is the distance between the two objects, \(r_{cutoff}\) is the global cutoff distance, and \(d\) is an optional decay term.

Automatically updates when running on a CUDA device.

Parameters:
  • A (ParticleType) – first type

  • B (ParticleType) – second type

  • name (string) – name of species

  • k (float) – transport coefficient

  • target (float) – target concentration

  • decay (float, optional) – optional decay. Defaults to 0.0

  • cutoff (float, optional) – optional cutoff distance. Defaults to global cutoff

Return type:

Fluxes

Returns:

Fluxes*

Bonds

class tissue_forge.Bond

Bonds apply a potential to a particular set of particles.

If you’re building a model, you should probably instead be working with a BondHandle.

static create(potential, i, j, half_life=None, dissociation_energy=None, flags=0)

Construct a new bond handle and underlying bond.

Automatically updates when running on a CUDA device.

Parameters:
  • potential (Potential) – bond potential

  • i (ParticleHandle) – ith particle

  • j (ParticleHandle) – jth particle

  • half_life (float, optional) – bond half life

  • dissociation_energy (float, optional) – dissociation energy

  • flags (int, optional) – bond flags

toString()

Get a JSON string representation

static fromString(str)

Create from a JSON string representation.

The returned bond is not automatically registered with the engine.

Parameters:

str (string) –

__reduce__()

Helper for pickle.

class tissue_forge.BondHandle(*args)

Handle to a bond

This is a safe way to work with a bond.

Overload 1:

Construct a new bond handle and do nothing Subsequent usage will require a call to ‘init’


Overload 2:

Construct a new bond handle from an existing bond id

Parameters:

id (int) – id of existing bond


Overload 3:

Construct a new bond handle and underlying bond.

Automatically updates when running on a CUDA device.

Parameters:
  • potential (Potential) – bond potential

  • i (int) – id of ith particle

  • j (int) – id of jth particle

  • half_life (float) – bond half life

  • bond_energy (float) – bond energy

  • flags (int) – bond flags

property length

bond length

property energy

bond energy

property parts

bonded particles

property potential

bond potential

property id

bond id

property dissociation_energy

bond dissociation energy

property half_life

bond half life

property style

bond style

property age

bond age

has(*args)

Overload 1: Test whether the bond has an id


Overload 2: Test whether the bond has a particle

__str__() str

Return str(self).

__getitem__(index: int)
__contains__(item)
__lt__(rhs) bool

Return self<value.

__gt__(rhs) bool

Return self>value.

__le__(rhs) bool

Return self<=value.

__ge__(rhs) bool

Return self>=value.

__eq__(rhs) bool

Return self==value.

__ne__(rhs) bool

Return self!=value.

get()

Gets the underlying bond

Return type:

Bond

Returns:

bond, if available

static pairwise(pot, parts, cutoff, ppairs, half_life, bond_energy, flags)

Apply bonds to a list of particles.

Automatically updates when running on a CUDA device.

Parameters:
  • pot (Potential) – the potential of the created bonds

  • parts (ParticleList) – list of particles

  • cutoff (float) – cutoff distance of particles that are bonded

  • ppairs (std::vector< std::pair< TissueForge::ParticleType *,TissueForge::ParticleType * > *,std::allocator< std::pair< TissueForge::ParticleType *,TissueForge::ParticleType * > * > >) – type pairs of bonds

  • half_life (float) – bond half life

  • bond_energy (float) – bond energy

  • flags (int) – bond flags

Return type:

std::vector< TissueForge::BondHandle,std::allocator< TissueForge::BondHandle > >

Returns:

created bonds

destroy()

Destroy the bond.

Automatically updates when running on a CUDA device.

static items()

Gets all bonds in the universe

decays()

Tests whether this bond decays

Return type:

boolean

Returns:

true when the bond should decay

class tissue_forge.Angle

A bond concerning an angle

If you’re building a model, you should probably instead be working with a AngleHandle.

static create(potential, p1, p2, p3, flags=0)

Creates an angle bond.

Automatically updates when running on a CUDA device.

Parameters:
  • potential (Potential) – potential of the bond

  • p1 (ParticleHandle) – first outer particle

  • p2 (ParticleHandle) – center particle

  • p3 (ParticleHandle) – second outer particle

  • flags (int, optional) – angle flags

Return type:

AngleHandle

Returns:

AngleHandle*

toString()

Get a JSON string representation

static fromString(str)

Create from a JSON string representation.

The returned angle is not automatically registered with the engine.

Parameters:

str (string) –

__reduce__()

Helper for pickle.

class tissue_forge.AngleHandle(*args)

A handle to an angle bond

This is a safe way to work with an angle bond.

Construct a new angle handle from an existing angle id

Parameters:

id – id of existing angle

property angle

angle angle

property energy

angle energy

property parts

bonded particles

property potential

angle potential

property id

angle id

property dissociation_energy

bond dissociation energy

property half_life

angle half life

property style

angle style

property age

angle age

has(*args)

Overload 1: Test whether the bond has an id


Overload 2: Test whether the bond has a particle

__str__() str

Return str(self).

__getitem__(index: int)
__contains__(item)
__lt__(rhs) bool

Return self<value.

__gt__(rhs) bool

Return self>value.

__le__(rhs) bool

Return self<=value.

__ge__(rhs) bool

Return self>=value.

__eq__(rhs) bool

Return self==value.

__ne__(rhs) bool

Return self!=value.

get()

Gets the angle of this handle

Return type:

Angle

Returns:

angle, if available

destroy()

Destroy the angle.

Automatically updates when running on a CUDA device.

static items()

Gets all angles in the universe

decays()

Tests whether this bond decays

Return type:

boolean

Returns:

true when the bond should decay

class tissue_forge.Dihedral

The dihedral structure

static create(potential, p1, p2, p3, p4)

Creates a dihedral bond

Parameters:
Return type:

DihedralHandle

Returns:

DihedralHandle*

toString()

Get a JSON string representation

static fromString(str)

Create from a JSON string representation.

The returned dihedral is not automatically registered with the engine.

Parameters:

str (string) –

__reduce__()

Helper for pickle.

class tissue_forge.DihedralHandle(*args)

A handle to a dihedral bond

This is a safe way to work with a dihedral bond.

Construct a new dihedral handle from an existing dihedral id

Parameters:

id – id of existing dihedral

property angle

dihedral angle

property energy

dihedral energy

property parts

bonded particles

property potential

dihedral potential

property id

dihedral id

property dissociation_energy

bond dissociation energy

property half_life

dihedral half life

property style

dihedral style

property age

dihedral age

get()

Gets the dihedral of this handle

Return type:

Dihedral

Returns:

dihedral, if available

has(*args)

Overload 1: Test whether the bond has an id


Overload 2: Test whether the bond has a particle

__str__() str

Return str(self).

__getitem__(index: int)
__contains__(item)
__lt__(rhs) bool

Return self<value.

__gt__(rhs) bool

Return self>value.

__le__(rhs) bool

Return self<=value.

__ge__(rhs) bool

Return self>=value.

__eq__(rhs) bool

Return self==value.

__ne__(rhs) bool

Return self!=value.

destroy()

Destroy the dihedral

static items()

Gets all dihedrals in the universe

decays()

Tests whether this bond decays

Return type:

boolean

Returns:

true when the bond should decay

Binding

tissue_forge.bind.particles(p, a, b)

Bind a potential to a pair of particles

Parameters:
  • p (Potential) – The potential

  • a (Particle) – The first particle

  • b (Particle) – The second particle

Return type:

int

Returns:

HRESULT

tissue_forge.bind.types(p, a, b, bound=False)

Bind a potential to a pair of particle types.

Automatically updates when running on a CUDA device.

Parameters:
  • p (Potential) – The potential

  • a (ParticleType) – The first type

  • b (ParticleType) – The second type

  • bound (boolean, optional) – Flag signifying whether this potential exclusively operates on particles of different clusters, optional

Return type:

int

Returns:

HRESULT

tissue_forge.bind.boundary_conditions(p, t)

Bind a potential to a pair of particle type and all boundary conditions.

Automatically updates when running on a CUDA device.

Parameters:
  • p (Potential) – The potential

  • t (ParticleType) – The particle type

Return type:

int

Returns:

HRESULT

tissue_forge.bind.boundary_condition(p, bc, t)

Bind a potential to a pair of particle type and a boundary conditions.

Automatically updates when running on a CUDA device.

Parameters:
  • p (Potential) – The potential

  • bc (BoundaryCondition) – The boundary condition

  • t (ParticleType) – The particle type

Return type:

int

Returns:

HRESULT

tissue_forge.bind.force(*args)

Overload 1:

Bind a force to a particle type

Parameters:
  • force (Force) – The force

  • a_type (ParticleType) – The particle type

Return type:

int

Returns:

HRESULT


Overload 2:

Bind a force to a particle type with magnitude proportional to a species amount

Parameters:
  • force (Force) – The force

  • a_type (ParticleType) – The particle type

  • coupling_symbol (string) – The symbol of the species

Return type:

int

Returns:

HRESULT

tissue_forge.bind.bonds(potential, particles, cutoff, pairs=None, half_life=None, bond_energy=None, flags=0)

Reactions and Species

class tissue_forge.state.Species(*args)
__str__() str

Return str(self).

toString()

Get a JSON string representation

Return type:

string

Returns:

std::string

static fromString(str)

Create from a JSON string representation.

Parameters:

str (string) –

Return type:

Species

Returns:

Species*

__reduce__()

Helper for pickle.

property id: str
property name: str
property species_type: str
property compartment: str
property initial_amount: float
property initial_concentration: float
property substance_units: str
property spatial_size_units: str
property units: str
property has_only_substance_units: bool
property boundary_condition: bool
property charge: int
property constant: bool
property conversion_factor: str
class tissue_forge.state.SpeciesValue(state_vector, index)
property boundary_condition: bool
property initial_amount: float
property initial_concentration: float
property constant: bool
property value: float
secrete(amount, to=None, distance=None)

Secrete this species into a neighborhood.

Requires either a list of neighboring particles or neighborhood distance.

Parameters:
  • amount (float) – Amount to secrete.

  • to (ParticleList) – Optional list of particles to secrete to.

  • distance (float) – Neighborhood distance.

Returns:

Amount actually secreted, accounting for availability and other subtleties.

Return type:

float

class tissue_forge.state.SpeciesList
__str__() str

Return str(self).

__len__() int
__getattr__(item: str)
__setattr__(item: str, value) None

Implement setattr(self, name, value).

__getitem__(item) _state_Species
__setitem__(item, value) None
item(*args)

Overload 1:

Get a species by index

Parameters:

index (int) – index of the species

Return type:

Species

Returns:

Species*


Overload 2:

Get a species by name

Parameters:

s (string) – name of species

Return type:

Species

Returns:

Species*

insert(*args)

Overload 1:

Insert a species

Return type:

int

Returns:

HRESULT


Overload 2:

Insert a species by name

Parameters:

s (string) – name of the species

Return type:

int

Returns:

HRESULT

toString()

Get a JSON string representation

Return type:

string

Returns:

std::string

static fromString(str)

Create from a JSON string representation.

Parameters:

str (string) –

Return type:

SpeciesList

Returns:

SpeciesList*

__reduce__()

Helper for pickle.

class tissue_forge.state.StateVector(*args)
__str__() str

Return str(self).

__len__() int
__getattr__(item: str)
__setattr__(item: str, value: float) None

Implement setattr(self, name, value).

__getitem__(item: int)
__setitem__(item: int, value: float) None
toString()

Get a JSON string representation

Return type:

string

Returns:

std::string

static fromString(str)

Create from a JSON string representation.

Parameters:

str (string) –

Return type:

StateVector

Returns:

StateVector*

__reduce__()

Helper for pickle.

species

Species of the state vector

Events

class tissue_forge.event.Event(invokeExecutor, predicateExecutor=None)
invoke()

What occurs during an event. Typically, this invokes an underlying specialized method returns 0 if OK and 1 on error.

property last_fired

Record of last time fired

predicate()

Evaluates an event predicate, returns 0 if the event should not fire, 1 if the event should, and a negative value on error. A predicate without a defined predicate method always returns 0

remove()

Designates event for removal

property thisown

The membership flag

property times_fired

Record of how many times fired

tissue_forge.event.on_event(invoke_method, predicate_method=None)

Creates and registers an event using prescribed invoke and predicate python function executors

Parameters:
  • invoke_method (PyObject) – an invoke method; evaluated when an event occurs. Takes an event.Event instance as argument and returns 0 on success, 1 on error

  • predicate_method – optional predicate method; decides if an event occurs. Takes a Event instance as argument and returns 1 to trigger event, -1 on error and 0 otherwise

class tissue_forge.event.TimeEvent(period, invokeExecutor, predicateExecutor=None, nextTimeSetter=None, start_time=0, end_time=-1)
property end_time

End time of evaluations

eval(time)
property flags
invoke()

What occurs during an event. Typically, this invokes an underlying specialized method returns 0 if OK and 1 on error.

property last_fired

Record of last time fired

property next_time

Next time of evaluation

property period

Period of evaluation

predicate()

Evaluates an event predicate, returns 0 if the event should not fire, 1 if the event should, and a negative value on error. A predicate without a defined predicate method always returns 0

remove()

Designates event for removal

property start_time

Start time of evaluations

property thisown

The membership flag

property times_fired

Record of how many times fired

tissue_forge.event.on_time(period, invoke_method, predicate_method=None, distribution='default', start_time=0.0, end_time=-1.0)

Like on_event, but for an event that occurs at regular intervals.

Parameters:
  • period (float) – period of event

  • invoke_method (PyObject) – an invoke method; evaluated when an event occurs. Takes an TimeEvent instance as argument and returns 0 on success, 1 on error

  • predicate_method – optional predicate method; decides if an event occurs. Takes a TimeEvent instance as argument and returns 1 to trigger event, -1 on error and 0 otherwise

  • distribution (str) – distribution by which the next event time is selected

  • start_time (float) – time after which the event can occur

  • end_time (float) – time before which the event can occur; a negative value is interpreted as until ‘forever’

class tissue_forge.event.ParticleEvent(*args)
eval(time)
property flags
invoke()

What occurs during an event. Typically, this invokes an underlying specialized method returns 0 if OK and 1 on error.

property last_fired

Record of last time fired

predicate()

Evaluates an event predicate, returns 0 if the event should not fire, 1 if the event should, and a negative value on error. A predicate without a defined predicate method always returns 0

remove()

Designates event for removal

setParticleEventParticleSelector(*args)
property targetParticle

Target particle of an event evaluation

property targetType

Target particle type of this event

property thisown

The membership flag

property times_fired

Record of how many times fired

tissue_forge.event.on_particle(ptype, invoke_method, predicate_method=None, selector='default', single: bool = False)

Like on_event, but for a particle of a particular particle type.

Parameters:
  • ptype (ParticleType) – the type of particle to select

  • invoke_method (PyObject) – an invoke method; evaluated when an event occurs. Takes an ParticleEvent instance as argument and returns 0 on success, 1 on error

  • predicate_method – optional predicate method; decides if an event occurs. Takes a ParticleEvent instance as argument and returns 1 to trigger event, -1 on error and 0 otherwise

  • selector (str) – name of particle selector

  • single (bool) – flag to only trigger event once and then return

class tissue_forge.event.ParticleTimeEvent(*args)
property end_time

Time at which evaluations stop

eval(time)
property flags
invoke()

What occurs during an event. Typically, this invokes an underlying specialized method returns 0 if OK and 1 on error.

property last_fired

Record of last time fired

property next_time

Next time at which an evaluation occurs

property period

Period of event evaluations

predicate()

Evaluates an event predicate, returns 0 if the event should not fire, 1 if the event should, and a negative value on error. A predicate without a defined predicate method always returns 0

remove()

Designates event for removal

property start_time

Time at which evaluations begin

property targetParticle

Target particle of an event evaluation

property targetType

Target particle type of this event

property thisown

The membership flag

property times_fired

Record of how many times fired

tissue_forge.event.on_particletime(ptype, period, invoke_method, predicate_method=None, distribution='default', start_time=0.0, end_time=-1.0, selector='default')

A combination of on_time and on_particle.

Parameters:
  • ptype (ParticleType) – the type of particle to select

  • period (float) – period of event

  • invoke_method (PyObject) – an invoke method; evaluated when an event occurs. Takes an TimeEvent instance as argument and returns 0 on success, 1 on error

  • predicate_method – optional predicate method; decides if an event occurs. Takes a TimeEvent instance as argument and returns 1 to trigger event, -1 on error and 0 otherwise

  • distribution (str) – distribution by which the next event time is selected

  • start_time (str) – time after which the event can occur

  • end_time (float) – time before which the event can occur; a negative value is interpreted as until ‘forever’

  • selector (str) – name of particle selector

class tissue_forge.event.KeyEvent(glfw_event=None)
static addDelegate(_delegate)

Adds an event delegate

Parameters:

_delegate (int) – delegate to add

Return type:

int

Returns:

handle for future getting and removing

static addHandler(_handler)

Adds an event handler

Parameters:

_handler (int) – handler to add

Return type:

int

Returns:

handle for future getting and removing

static getDelegate(handle)

Get an event delegate

Parameters:

handle (int) – delegate handle

Return type:

int

Returns:

delegate if handle is valid, otherwise NULL

static getHandler(handle)

Get an event handler

Parameters:

handle (int) – handler handle

Return type:

int

Returns:

handler if handle is valid, otherwise NULL

property glfw_event
static invoke(*args)
keyAlt()
keyCtrl()
keyName()
keyShift()
property key_alt: bool

Flag for whether Alt key is pressed

property key_ctrl: bool

Flag for whether Ctrl key is pressed

property key_name: str

Key pressed for this event

property key_shift: bool

Flag for whether Shift key is pressed

static removeDelegate(handle)

Remove an event delegate

Parameters:

handle (int) – delegate handle

Return type:

boolean

Returns:

true when delegate is removed

Return type:

boolean

Returns:

false when handle is invalid

static removeHandler(handle)

Remove an event handler

Parameters:

handle (int) – handler handle

Return type:

boolean

Returns:

true when handler is removed

Return type:

boolean

Returns:

false when handle is invalid

property thisown

The membership flag

tissue_forge.event.on_keypress(invoke_method)

Registers a callback for handling keyboard events

Parameters:

invoke_method (PyObject) – an invoke method; evaluated when an event occurs. Takes an KeyEvent instance as argument and returns None

Lattices

class tissue_forge.lattice.BondRule(func: Callable[[ParticleHandle, ParticleHandle], BondHandle], part_ids: Tuple[int, int], cell_offset: Tuple[int, int, int])

Simple container for info to create a bond when constructing a lattice

Parameters:
  • func – function of func(p1, p2) that accepts two particle handles and returns a newly created bond.

  • part_ids – pair of particle ids in current current and other unit cell.

  • cell_offset – offset vector of other unit cell relative to current unit cell.

class tissue_forge.lattice.unitcell(N: int, a1: List[float], a2: List[float], a3: List[float], dimensions: int = 3, position: List[List[float]] | None = None, types: List[ParticleType] | None = None, bonds: List[BondRule] | None = None)

A unit cell

A unit cell is a box definition (a1, a2, a3, dimensions), and particle properties for N particles. You do not need to specify all particle properties. Any property omitted will be initialized to defaults. The function create_lattice initializes the system with many copies of a unit cell.

unitcell is a completely generic unit cell representation. See other classes in the lattice module for convenience wrappers for common lattices.

Example:

uc = lattice.unitcell(N=2,
                      a1=[1, 0, 0],
                      a2=[0.2, 1.2, 0],
                      a3=[-0.2, 0, 1.0],
                      dimensions=3,
                      position=[[0, 0, 0], [0.5, 0.5, 0.5]],
                      types=[A, B])
Note:

a1, a2, a3 must define a right handed coordinate system.

Parameters:
  • N (int) – Number of particles in the unit cell.

  • a1 (List[float]) – Lattice vector (3-vector).

  • a2 (List[float]) – Lattice vector (3-vector).

  • a3 (List[float]) – Lattice vector (3-vector).

  • dimensions (int) – Dimensionality of the lattice (2 or 3).

  • position (List[List[float]]) – List of particle positions.

  • types (List[tf.ParticleType]) – List of particle types

  • bonds (List[BondRule]) – bond constructors rules

tissue_forge.lattice.sc(a: float, types: ParticleType | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True, True)) unitcell

Create a unit cell for a simple cubic lattice (3D).

The simple cubic lattice unit cell has one particle:

  • [0, 0, 0]

And the box matrix:

  • [[a, 0, 0] [0, a, 0] [0, 0, a]]

Example:

uc = tissue_forge.lattice.sc(1.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:
  • a – lattice constant

  • types – particle type

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds in the 1-, 2-, and 3-directions

Returns:

a simple cubic lattice unit cell

tissue_forge.lattice.bcc(a: float, types: ParticleType | List[ParticleType] | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True)) unitcell

Create a unit cell for a body centered cubic lattice (3D).

The body centered cubic lattice unit cell has two particles:

  • [0, 0, 0]

  • [a/2, a/2, a/2]

And the box matrix:

  • [[a, 0, 0] [0, a, 0] [0, 0, a]]

Example:

uc = tissue_forge.lattice.bcc(1.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:
  • a – lattice constant

  • types – particle type or list of particle types

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds - between the corner particles - between the corner and center particles

Returns:

a body centered cubic lattice unit cell

tissue_forge.lattice.fcc(a: float, types: ParticleType | List[ParticleType] | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True)) unitcell

Create a unit cell for a face centered cubic lattice (3D).

The face centered cubic lattice unit cell has four particles:

  • [0, 0, 0]

  • [0, a/2, a/2]

  • [a/2, 0, a/2]

  • [a/2, a/2, 0]]

And the box matrix:

  • [[a, 0, 0] [0, a, 0] [0, 0, a]]

Example:

uc = tissue_forge.lattice.fcc(1.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:
  • a – lattice constant

  • types – particle type or list of particle types

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds - between the corner particles - between the corner and the center particles

Returns:

a face centered cubic lattice unit cell

tissue_forge.lattice.sq(a: float, types: ParticleType | List[ParticleType] | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True, False)) unitcell

Create a unit cell for a square lattice (2D).

The square lattice unit cell has one particle:

  • [0, 0]

And the box matrix:

  • [[a, 0] [0, a]]

Example:

uc = tissue_forge.lattice.sq(1.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:
  • a – lattice constant

  • types – particle type or list of particle types

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds along the 1-, 2- and 3-directions

Returns:

a square lattice unit cell

tissue_forge.lattice.hex2d(a: float, types: ParticleType | List[ParticleType] | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True, False)) unitcell

Create a unit cell for a hexagonal lattice (2D).

The hexagonal lattice unit cell has two particles:

  • [0, 0]

  • [0, a*sqrt(3)/2]

And the box matrix:

  • [[a, 0] [0, a*sqrt(3)]]

Example:

uc = tissue_forge.lattice.hex2d(1.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:
  • a – lattice constant

  • types – particle type or list of particle types

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds along the 1-, 2- and 3-directions

Returns:

a hexagonal lattice unit cell

tissue_forge.lattice.hcp(a: float, c: float | None = None, types: ParticleType | List[ParticleType] | None = None, bond: Callable[[ParticleHandle, ParticleHandle], BondHandle] | List[Callable[[ParticleHandle, ParticleHandle], BondHandle]] | None = None, bond_vector: Tuple[bool] = (True, True, True)) unitcell

Create a unit cell for a hexagonal close pack lattice (3D).

The hexagonal close pack lattice unit cell has seven particles:

  • [0, a*sqrt(3)/2, 0]

  • [a/2, 0, 0]

  • [a, a*sqrt(3)/2, 0]

  • [a*3/2, 0, 0]

  • [a/2, a*2/sqrt(3), c/2]

  • [a, a/2/sqrt(3), c/2]

  • [a*3/2, a*2/sqrt(3), c/2]

And the box matrix:

  • [[2*a, 0, 0] [0, a*sqrt(3), 0] [0, 0, c]]

Example:

uc = tissue_forge.lattice.hcp(1.0, 2.0, A, lambda i, j: tf.Bond.create(pot, i, j, dissociation_energy=100.0))
Parameters:
  • a – lattice constant

  • c – height of lattice (default a)

  • types – particle type or list of particle types

  • bond – bond constructor(s)

  • bond_vector – flags for creating bonds - between the outer particles - between the inner particles - between the outer and inner particles

Returns:

a hexagonal close pack lattice unit cell

tissue_forge.lattice.create_lattice(uc: unitcell, n: int | List[int], origin: List[float] | None = None) ndarray

Create a lattice

Takes a unit cell and replicates it the requested number of times in each direction. A generic unitcell may have arbitrary vectors a1, a2, and a3. create_lattice will rotate the unit cell so that a1 points in the x direction and a2 is in the xy plane so that the lattice may be represented as a simulation box. When n is a single value, the lattice is replicated n times in each direction. When n is a list, the lattice is replicated n[i] times in each ``i``th direction.

Examples:

tissue_forge.lattice.create_lattice(uc=tissue_forge.lattice.sc(a=1.0), n=[2,4,2])
tissue_forge.lattice.create_lattice(uc=tissue_forge.lattice.bcc(a=1.0), n=10)
tissue_forge.lattice.create_lattice(uc=tissue_forge.lattice.sq(a=1.2), n=[100,10])
tissue_forge.lattice.create_lattice(uc=tissue_forge.lattice.hex2d(a=1.0), n=[100,58])
Parameters:
  • uc – unit cell

  • n – number of unit cells to create along all/each direction(s)

  • origin – origin to begin creating lattice (default centered about simulation origin)

Returns:

particles created in every unit cell

Style

class tissue_forge.rendering.ColorMapper(*args)
property min_val

minimum value of map

property max_val

maximum value of map

property has_map_particle: bool
property has_map_angle: bool
property has_map_bond: bool
property has_map_dihedral: bool
clear_map_particle()

Clear the particle map

clear_map_angle()

Clear the angle map

clear_map_bond()

Clear the bond map

clear_map_dihedral()

Clear the dihedral map

set_map_particle_position_x()

Set the particle map to x-coordinate of particle position

set_map_particle_position_y()

Set the particle map to y-coordinate of particle position

set_map_particle_position_z()

Set the particle map to z-coordinate of particle position

set_map_particle_velocity_x()

Set the particle map to x-component of particle velocity

set_map_particle_velocity_y()

Set the particle map to y-component of particle velocity

set_map_particle_velocity_z()

Set the particle map to z-component of particle velocity

set_map_particle_speed()

Set the particle map to particle speed

set_map_particle_force_x()

Set the particle map to x-component of particle force

set_map_particle_force_y()

Set the particle map to y-component of particle force

set_map_particle_force_z()

Set the particle map to z-component of particle force

set_map_particle_species(pType, name)

Set the particle map to a species value

Parameters:
  • pType (ParticleType) – particle type

  • name (string) – species name

set_map_angle_angle()

Set the angle map to angle

set_map_angle_angle_eq()

Set the angle map to angle from equilibrium

set_map_bond_length()

Set the bond map to length

set_map_bond_length_eq()

Set the bond map to length from equilibrium

set_map_dihedral_angle()

Set the dihedral map to angle

set_map_dihedral_angle_eq()

Set the dihedral map to angle from equilibrium

class tissue_forge.rendering.Style(*args)
property color

Default color

property visible: bool

Visibility flag

property colormap: str

Name of color map

property mapper

Color mapper of this style

setColor(colorName)

Set the color by name

Parameters:

colorName (string) – name of color

Return type:

int

Returns:

HRESULT

toString()

Get a JSON string representation

Return type:

string

Returns:

std::string

static fromString(str)

Create from a JSON string representation.

Parameters:

str (string) –

Return type:

Style

Returns:

Style*

__reduce__()

Helper for pickle.

Rendering

class tissue_forge.rendering.ClipPlane(i)
property index

Index of the clip plane. Less than zero if clip plane has been destroyed.

property point: fVector3
property normal: fVector3
getEquation()

Get the coefficients of the plane equation of the clip plane

Return type:

fVector4

Returns:

fVector4

setEquation(*args)

Overload 1:

Set the coefficients of the plane equation of the clip plane

Parameters:

pe (fVector4) –

Return type:

int

Returns:

HRESULT


Overload 2:

Set the coefficients of the plane equation of the clip plane using a point on the plane and its normal

Parameters:
  • point (fVector3) – plane point

  • normal (fVector3) – plane normal vector

Return type:

int

Returns:

HRESULT

destroy()

Destroy the clip plane

Return type:

int

Returns:

HRESULT

class tissue_forge.rendering.ClipPlanes
static len()

Get the number of clip planes

Return type:

int

Returns:

int

static getClipPlaneEquation(index)

Get the coefficients of the equation of a clip plane

Parameters:

index (int) – index of the clip plane

Return type:

fVector4

Returns:

const fVector4&

static setClipPlaneEquation(index, pe)

Set the coefficients of the equation of a clip plane.

The clip plane must already exist

Parameters:
  • index (int) – index of the clip plane

  • pe (fVector4) – coefficients of the plane equation of the clip plane

Return type:

int

Returns:

HRESULT

static item(index)

Get a clip plane by index

Parameters:

index (int) – index of the clip plane

Return type:

ClipPlane

Returns:

ClipPlane

static create(*args)

Overload 1:

Create a clip plane

Parameters:

pe (fVector4) – coefficients of the equation of the plane

Return type:

ClipPlane

Returns:

ClipPlane


Overload 2:

Create a clip plane

Parameters:
  • point (fVector3) – point on the clip plane

  • normal (fVector3) – normal of the clip plane

Return type:

ClipPlane

Returns:

ClipPlane

System

tissue_forge.system.print_performance_counters()
tissue_forge.system.context_has_current()
tissue_forge.system.context_make_current()
tissue_forge.system.context_release()
tissue_forge.system.camera_move_to(*args)

Overload 1:

Set the camera view parameters

Parameters:
  • eye (FVector3) – camera eye

  • center (FVector3) – view center

  • up (FVector3) – view upward direction

Return type:

int

Returns:

HRESULT


Overload 2:

Set the camera view parameters

Parameters:
  • center (FVector3) – target camera view center position

  • rotation (FQuaternion) – target camera rotation

  • zoom (float) – target camera zoom

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_view_bottom()

Move the camera to view the domain from the bottm

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_view_top()

Move the camera to view the domain from the top

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_view_left()

Move the camera to view the domain from the left

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_view_right()

Move the camera to view the domain from the right

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_view_back()

Move the camera to view the domain from the back

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_view_front()

Move the camera to view the domain from the front

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_reset()

Reset the camera

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_rotate_mouse(mousePos)
tissue_forge.system.camera_translate_mouse(mousePos)
tissue_forge.system.camera_translate_down()

Translate the camera down

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_translate_up()

Translate the camera up

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_translate_right()

Translate the camera right

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_translate_left()

Translate the camera left

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_translate_forward()

Translate the camera forward

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_translate_backward()

Translate the camera backward

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_rotate_down()

Rotate the camera down

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_rotate_up()

Rotate the camera up

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_rotate_left()

Rotate the camera left

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_rotate_right()

Rotate the camera right

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_roll_left()

Roll the camera left

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_roll_right()

Rotate the camera right

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_zoom_in()

Zoom the camera in

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_zoom_out()

Zoom the camera out

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_init_mouse(mousePos)
tissue_forge.system.camera_translate_by(trans)
tissue_forge.system.camera_zoom_by(delta)

Zoom the camera by an increment in distance.

Positive values zoom in.

Parameters:

delta (float) – zoom increment

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_zoom_to(distance)

Zoom the camera to a distance.

Parameters:

distance (float) – zoom distance

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_rotate_to_axis(axis, distance)

Rotate the camera to a point from the view center a distance along an axis.

Only rotates the view to the given eye position.

Parameters:
  • axis (FVector3) – axis from the view center

  • distance (float) – distance along the axis

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_rotate_to_euler_angle(angles)

Rotate the camera to a set of Euler angles.

Rotations are Z-Y-X.

Parameters:

angles (FVector3) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_rotate_by_euler_angle(angles)

Rotate the camera by a set of Euler angles.

Rotations are Z-Y-X.

Parameters:

angles (FVector3) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.camera_center()

Get the current camera view center position

Return type:

FVector3

Returns:

FVector3

tissue_forge.system.camera_rotation()

Get the current camera rotation

Return type:

FQuaternion

Returns:

FQuaternion

tissue_forge.system.camera_zoom()

Get the current camera zoom

Return type:

float

Returns:

float

tissue_forge.system.get_renderer()

Get the universe renderer

Return type:

TissueForge::rendering::UniverseRenderer

Returns:

struct rendering::UniverseRenderer*

tissue_forge.system.get_rendering_3d_bonds()

Get whether bonds are renderered with 3D objects

tissue_forge.system.set_rendering_3d_bonds(_flag)

Set whether bonds are renderered with 3D objects

tissue_forge.system.toggle_rendering_3d_bonds()

Toggle whether bonds are renderered with 3D objects

tissue_forge.system.get_rendering_3d_angles()

Get whether angles are renderered with 3D objects

tissue_forge.system.set_rendering_3d_angles(_flag)

Set whether angles are renderered with 3D objects

tissue_forge.system.toggle_rendering_3d_angles()

Toggle whether angles are renderered with 3D objects

tissue_forge.system.get_rendering_3d_dihedrals()

Get whether dihedrals are renderered with 3D objects

tissue_forge.system.set_rendering_3d_dihedrals(_flag)

Set whether dihedrals are renderered with 3D objects

tissue_forge.system.toggle_rendering_3d_dihedrals()

Toggle whether dihedrals are renderered with 3D objects

tissue_forge.system.set_rendering_3d_all(_flag)

Set whether bonds, angle and dihedrals are renderered with 3D objects

tissue_forge.system.toggle_rendering_3d_all()

Toggle whether bonds, angle and dihedrals are renderered with 3D objects

tissue_forge.system.get_ambient_color()

Get the ambient color

Return type:

FVector3

Returns:

FVector3

tissue_forge.system.set_ambient_color(*args)

Overload 1:

Set the ambient color

Parameters:

color (FVector3) –

Return type:

int

Returns:

HRESULT


Overload 2:

Set the ambient color of a subrenderer

Parameters:
  • color (FVector3) –

  • srFlag (int) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.get_diffuse_color()

Get the diffuse color

Return type:

FVector3

Returns:

FVector3

tissue_forge.system.set_diffuse_color(*args)

Overload 1:

Set the diffuse color

Parameters:

color (FVector3) –

Return type:

int

Returns:

HRESULT


Overload 2:

Set the diffuse color of a subrenderer

Parameters:
  • color (FVector3) –

  • srFlag (int) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.get_specular_color()

Get specular color

Return type:

FVector3

Returns:

FVector3

tissue_forge.system.set_specular_color(*args)

Overload 1:

Set the specular color

Parameters:

color (FVector3) –

Return type:

int

Returns:

HRESULT


Overload 2:

Set the specular color of a subrenderer

Parameters:
  • color (FVector3) –

  • srFlag (int) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.get_shininess()

Get the shininess

Return type:

float

Returns:

float

tissue_forge.system.set_shininess(*args)

Overload 1:

Set the shininess

Parameters:

shininess (float) –

Return type:

int

Returns:

HRESULT


Overload 2:

Set the shininess of a subrenderer

Parameters:
  • shininess (float) –

  • srFlag (int) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.get_grid_color()

Get the grid color

Return type:

FVector3

Returns:

FVector3

tissue_forge.system.set_grid_color(color)

Set the grid color

Parameters:

color (FVector3) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.get_scene_box_color()

Get the scene box color

Return type:

FVector3

Returns:

FVector3

tissue_forge.system.set_scene_box_color(color)

Set the scene box color

Parameters:

color (FVector3) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.get_light_direction()

Get the light direction

Return type:

FVector3

Returns:

FVector3

tissue_forge.system.set_light_direction(*args)

Overload 1:

Set the light direction

Parameters:

lightDir (FVector3) –

Return type:

int

Returns:

HRESULT


Overload 2:

Set the light direction of a subrenderer

Parameters:
  • lightDir (FVector3) –

  • srFlag (int) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.get_light_color()

Get the light color

Return type:

FVector3

Returns:

FVector3

tissue_forge.system.set_light_color(*args)

Overload 1:

Set the light color

Parameters:

color (FVector3) –

Return type:

int

Returns:

HRESULT


Overload 2:

Set the light color of a subrenderer

Parameters:
  • color (FVector3) –

  • srFlag (int) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.get_background_color()

Get the background color

Return type:

FVector3

Returns:

FVector3

tissue_forge.system.set_background_color(color)

Set the background color

Parameters:

color (FVector3) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.decorated()

Test whether the rendered scene is decorated

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false

tissue_forge.system.decorate_scene(decorate)

Set flag to draw/not draw scene decorators (e.g., grid)

Parameters:

decorate (boolean) – flag; true says to decorate

Return type:

int

Returns:

HRESULT

tissue_forge.system.showing_discretization()

Test whether discretization is current shown

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false

tissue_forge.system.show_discretization(show)

Set flag to draw/not draw discretization

Parameters:

show (boolean) – flag; true says to show

Return type:

int

Returns:

HRESULT

tissue_forge.system.get_discretizationColor()

Get the current color of the discretization grid

Return type:

FVector3

Returns:

FVector3

tissue_forge.system.set_discretizationColor(color)

Set the color of the discretization grid

Parameters:

color (FVector3) –

Return type:

int

Returns:

HRESULT

tissue_forge.system.view_reshape(windowSize)
tissue_forge.system.performance_counters()
tissue_forge.system.egl_info()

Get EGL info

Return type:

string

Returns:

std::string

tissue_forge.system.image_data()
tissue_forge.system.is_terminal_interactive()

Test whether Tissue Forge is running in an interactive terminal

Return type:

boolean

Returns:

true if running in an interactive terminal

Return type:

boolean

Returns:

false

tissue_forge.system.is_jupyter_notebook()

Test whether Tissue Forge is running in a Jupyter notebook

Return type:

boolean

Returns:

true if running in a Jupyter notebook

Return type:

boolean

Returns:

false

tissue_forge.system.jwidget_init(args, kwargs)
tissue_forge.system.jwidget_run(args, kwargs)
tissue_forge.system.color_mapper_names()

Get all available color mapper names

tissue_forge.system.add_render_arrow(*args)

Overload 1:

Adds a vector visualization specification.

The passed pointer is borrowed. The client is responsible for maintaining the underlying data. The returned integer can be used to reference the arrow when doing subsequent operations with the renderer (e.g., removing an arrow from the scene).

Parameters:

arrow (ArrowData) – pointer to visualization specs

Return type:

int

Returns:

id of arrow according to the renderer


Overload 2:

Adds a vector visualization specification.

The passed pointer is borrowed. The client is responsible for maintaining the underlying data. The returned integer can be used to reference the arrow when doing subsequent operations with the renderer (e.g., removing an arrow from the scene).

Parameters:
  • position (FVector3) – position of vector

  • components (FVector3) – components of vector

  • style (Style) – style of vector

  • scale (float, optional) – scale of vector; defaults to 1.0

Return type:

std::pair< int,TissueForge::rendering::ArrowData * >

Returns:

id of arrow according to the renderer and arrow

tissue_forge.system.remove_render_arrow(arrowId)

Removes a vector visualization specification.

The removed pointer is only forgotten. The client is responsible for clearing the underlying data.

Parameters:

arrowId (int) – id of arrow according to the renderer

tissue_forge.system.get_render_arrow(arrowId)

Gets a vector visualization specification.

Parameters:

arrowId (int) – id of arrow according to the renderer

tissue_forge.system.cpu_info() dict

Dictionary of CPU info

tissue_forge.system.compile_flags() dict

Dictionary of CPU info

tissue_forge.system.gl_info() dict

Dictionary of OpenGL info

tissue_forge.system.screenshot(filepath: str, decorate: bool | None = None, bgcolor=None)

Save a screenshot of the current scene

Parameters:
  • filepath (str) – path of file to save

  • decorate (bool) – flag to decorate the scene in the screenshot

  • bgcolor (FVector3 or [float, float, float] or (float, float, float) or float) – background color of the scene in the screenshot

Return type:

int

Returns:

HRESULT

Logging

class tissue_forge.Logger

The Tissue Forge logger.

A set of static method for setting the logging level.

static setLevel(*args, **kwargs)

Set the Level objectsets the logging level to one a value from Logger::Level

Parameters:

level (int, optional) – logging level

static getLevel()

Get the Level objectget the current logging level.

Return type:

int

Returns:

int

static disableLogging()

Suppresses all logging output

static enableConsoleLogging(*args, **kwargs)

turns on console logging at the given level.

Parameters:

level (int, optional) – logging level

static disableConsoleLogging()

stops logging to the console, but file logging may continue.

static enableFileLogging(*args, **kwargs)

turns on file logging to the given file as the given level.

If fileName is an empty string, then nothing occurs.

Parameters:
  • fileName (string, optional) – path to log file

  • level (int, optional) – logging level

static disableFileLogging()

turns off file logging, but has no effect on console logging.

static getCurrentLevelAsString()

get the textural form of the current logging level.

Return type:

string

Returns:

std::string

static getFileName()

Get the File Name objectget the name of the currently used log file.

Return type:

string

Returns:

std::string

static levelToString(level)

gets the textual form of a logging level Enum for a given value.

static stringToLevel(str)

parses a string and returns a Logger::Level

static log(level, msg)

logs a message to the log.

Parameters:
  • level (int) – logging level

  • msg (string) – log message

Error Handling

class tissue_forge.Error
property err

Error code

property lineno

Originating line number

property fname

Originating file name

property func

Originating function name

__str__() str

Return str(self).

tissue_forge.err_occurred()

Check whether there is an error indicator.

tissue_forge.err_clear()

Clear the error indicators. If no error indicator is set, there is no effect.

tissue_forge.err_get_all()

Get all error indicators

tissue_forge.err_get_first()

Get the first error

tissue_forge.err_clear_first()

Clear the first error

tissue_forge.err_pop_first()

Get and clear the first error

Utilities

tissue_forge.random_point(kind: int, dr: float | None = None, phi0: float | None = None, phi1: float | None = None)

Get the coordinates of a random point in a kind of shape.

Currently supports PointsType.Sphere, PointsType.Disk, PointsType.SolidCube and PointsType.SolidSphere.

Parameters:
  • kind – kind of shape

  • dr – thickness parameter; only applicable to solid sphere kind

  • phi0 – angle lower bound; only applicable to solid sphere kind

  • phi1 – angle upper bound; only applicable to solid sphere kind

Returns:

coordinates of random points

Return type:

FVector3

tissue_forge.random_points(kind: int, n: int = 1, dr: float | None = None, phi0: float | None = None, phi1: float | None = None)

Get the coordinates of random points in a kind of shape.

Currently supports PointsType.Sphere, PointsType.Disk, PointsType.SolidCube and PointsType.SolidSphere.

Parameters:
  • kind – kind of shape

  • n – number of points

  • dr – thickness parameter; only applicable to solid sphere kind

  • phi0 – angle lower bound; only applicable to solid sphere kind

  • phi1 – angle upper bound; only applicable to solid sphere kind

Returns:

coordinates of random points

Return type:

list of FVector3

tissue_forge.points(kind, n=1)

Get the coordinates of uniform points in a kind of shape.

Currently supports ring and sphere.

Parameters:
  • kind (int) – kind of shape

  • n (int, optional) – number of points

Return type:

std::vector< TissueForge::FVector3,std::allocator< TissueForge::FVector3 > >

Returns:

std::vector<FVector3>

tissue_forge.filled_cube_uniform(corner1, corner2, num_parts_x: int = 2, num_parts_y: int = 2, num_parts_z: int = 2)

Get the coordinates of a uniformly filled cube.

Parameters:
  • corner1 (list of float or FVector3) – first corner of cube

  • corner2 (list of float or FVector3) – second corner of cube

  • num_parts_x – number of particles along x-direction of filling axes (>=2)

  • num_parts_y – number of particles along y-direction of filling axes (>=2)

  • num_parts_z – number of particles along z-direction of filling axes (>=2)

Returns:

coordinates of uniform points

Return type:

list of FVector3

tissue_forge.filled_cube_random(corner1, corner2, num_particles: int)

Get the coordinates of a randomly filled cube.

Parameters:
  • corner1 (list of float or FVector3) – first corner of cube

  • corner2 (list of float or FVector3) – second corner of cube

  • num_particles – number of particles

Returns:

coordinates of random points

Return type:

list of FVector3

tissue_forge.icosphere(subdivisions: int, phi0: float, phi1: float)

Get the coordinates of an icosphere.

Parameters:
  • subdivisions – number of subdivisions

  • phi0 – angle lower bound

  • phi1 – angle upper bound

Returns:

vertices and indices

Return type:

(list of FVector3, list of int)

tissue_forge.color3_names()

Get the names of all available colors

Return type:

list of str

tissue_forge.random_vector(mean, std)

Generates a randomly oriented vector with random magnitude with given mean and standard deviation according to a normal distribution.

Parameters:
  • mean (float) – magnitude mean

  • std (float) – magnitude standard deviation

Return type:

FVector3

Returns:

FVector3

tissue_forge.random_unit_vector()

Generates a randomly oriented unit vector.

Return type:

FVector3

Returns:

FVector3

tissue_forge.get_seed()

Get the current seed for the pseudo-random number generator

tissue_forge.set_seed(_seed=None)

Set the current seed for the pseudo-random number generator

Parameters:

_seed (int, optional) –

Return type:

int

Returns:

HRESULT

Metrics

tissue_forge.metrics.relative_position(pos, origin, comp_bc=True)

Computes the relative position with respect to an origin while optionally account for boundary conditions.

If boundaries along a dimension are periodic, then this chooses the relative coordinate closest to the origin.

Parameters:
  • pos (FVector3) – absolute position

  • origin (FVector3) – origin

  • comp_bc (boolean, optional) – flag to compensate for boundary conditions; default true

Return type:

FVector3

Returns:

FVector3 relative position with respect to the given origin

tissue_forge.metrics.neighborhood_particles(position, dist, comp_bc=True)

find all particles in a neighborhood defined by a point and distance

tissue_forge.metrics.calculate_virial(origin, radius, typeIds, tensor)

[in] origin of the sphere where we will comptute the local virial tensor. [in] include all partices a given radius in calculation. [in] vector of type ids to indlude in calculation, if empty, includes all particles. [out] result vector, writes a 3x3 matrix in a row-major in the given location.

If periodoc, we don’t include the periodic image cells, because we only calculate the forces within the simulation volume.

tissue_forge.metrics.particles_virial(parts, nr_parts, flags, tensor)

calculate the virial tensor for a specific list of particles. currently uses center of mass as origin, may change in the future with different flags.

flags currently ignored.

tissue_forge.metrics.particles_radius_of_gyration(parts, nr_parts, result)
Parameters:

result: – pointer to float to store result.

tissue_forge.metrics.particles_center_of_mass(parts, nr_parts, result)
Parameters:

result: – pointer to float[3] to store result

tissue_forge.metrics.particles_center_of_geometry(parts, nr_parts, result)
Parameters:

result: – pointer to float[3] to store result.

tissue_forge.metrics.particles_moment_of_inertia(parts, nr_parts, result)
Parameters:

result: – pointer to float[9] to store result.

tissue_forge.metrics.cartesian_to_spherical(postion, origin)

converts cartesian to spherical, writes spherical coords in to result array. return FVector3{radius, theta, phi};

tissue_forge.metrics.particle_neighbors(part, radius, typeIds, nr_parts, parts)

Searches and enumerates a location of space for all particles there.

Allocates a buffer, and stores the results there.

Parameters:
  • part (Particle) – the particle

  • radius (float) – [optional] the radius of the neighborhood

  • typeIds (std::set< short,std::less< short >,std::allocator< short > >) – [optional] set of type ids to include. If not given, gets all other parts within radius.

  • nr_parts (int) – [out] number of parts

  • parts (int) – [out] newly allocated buffer of particle ids.

tissue_forge.metrics.eigenvals(*args)

Overload 1:

Compute the eigenvalues of a 3x3 matrix

Parameters:
  • mat (FMatrix3) – the matrix

  • symmetric (boolean, optional) – flag signifying whether the matrix is symmetric

Return type:

FVector3

Returns:

eigenvalues


Overload 2:

Compute the eigenvalues of a 4x4 matrix

Parameters:
  • mat (FMatrix4) – the matrix

  • symmetric (boolean, optional) – flag signifying whether the matrix is symmetric

Return type:

FVector4

Returns:

eigenvalues

tissue_forge.metrics.eigenvecs_vals(*args)

Overload 1:

Compute the eigenvectors and eigenvalues of a 3x3 matrix

Parameters:
  • mat (FMatrix3) – the matrix

  • symmetric (boolean, optional) – flag signifying whether the matrix is symmetric

Return type:

std::pair< TissueForge::FVector3,TissueForge::FMatrix3 >

Returns:

eigenvalues, eigenvectors


Overload 2:

Compute the eigenvectors and eigenvalues of a 4x4 matrix

Parameters:
  • mat (FMatrix4) – the matrix

  • symmetric (boolean, optional) – flag signifying whether the matrix is symmetric

Return type:

std::pair< TissueForge::FVector4,TissueForge::FMatrix4 >

Returns:

eigenvalues, eigenvectors

Basic Tissue Forge Types

Tissue Forge uses some basic types that provide support and convenience methods for particular operations, especially concerning vector and tensor operations. Some of these types are completely native to Tissue Forge, and others constructed partially or completely from types distributed in various Tissue Forge dependencies (e.g., FVector3 from Vector3, from Magnum.

class tissue_forge.dVector2(*args)

A 2D vector with double elements

static xAxis(*args, **kwargs)

Get a vector in the X- (first-) direction of specified length

static yAxis(*args, **kwargs)

Get a vector in the Y- (second-) direction of specified length

static xScale(scale)

Get a scaling vector in the X- (first-) direction

static yScale(scale)

Get a scaling vector in the Y- (second-) direction

x(*args)

Overload 1: Get the X (first) component


Overload 2: Get the X (first) component

y(*args)

Overload 1: Get the Y (second) component


Overload 2: Get the Y (second) component

flipped()
dot(*args)
cross(other)

Get the cross product with another vector

angle(other)

angle made with another vector

__len__()
__iadd__(*args)
__add__(*args)
__isub__(*args)
__sub__(*args)
__imul__(*args)
__mul__(*args)
__itruediv__(*args)
__truediv__(*args)
length()

length of vector

normalized()

vector normalized

resized(length)

resize be a length

projected(other)

project onto another vector

projectedOntoNormalized(other)

project onto a normalized vector

distance(line_start_pt, line_end_pt)

distance from a line defined by two points

__getitem__(index: int)
__setitem__(index: int, val)
as_list() list

convert to a python list

__str__() str

Return str(self).

class tissue_forge.fVector2(*args)

A 2D vector with float elements

static xAxis(*args, **kwargs)

Get a vector in the X- (first-) direction of specified length

static yAxis(*args, **kwargs)

Get a vector in the Y- (second-) direction of specified length

static xScale(scale)

Get a scaling vector in the X- (first-) direction

static yScale(scale)

Get a scaling vector in the Y- (second-) direction

x(*args)

Overload 1: Get the X (first) component


Overload 2: Get the X (first) component

y(*args)

Overload 1: Get the Y (second) component


Overload 2: Get the Y (second) component

flipped()
dot(*args)
cross(other)

Get the cross product with another vector

angle(other)

angle made with another vector

__len__()
__iadd__(*args)
__add__(*args)
__isub__(*args)
__sub__(*args)
__imul__(*args)
__mul__(*args)
__itruediv__(*args)
__truediv__(*args)
length()

length of vector

normalized()

vector normalized

resized(length)

resize be a length

projected(other)

project onto another vector

projectedOntoNormalized(other)

project onto a normalized vector

distance(line_start_pt, line_end_pt)

distance from a line defined by two points

__getitem__(index: int)
__setitem__(index: int, val)
as_list() list

convert to a python list

__str__() str

Return str(self).

class tissue_forge.iVector2(*args)

A 2D vector with int elements

static xAxis(*args, **kwargs)

Get a vector in the X- (first-) direction of specified length

static yAxis(*args, **kwargs)

Get a vector in the Y- (second-) direction of specified length

static xScale(scale)

Get a scaling vector in the X- (first-) direction

static yScale(scale)

Get a scaling vector in the Y- (second-) direction

x(*args)

Overload 1: Get the X (first) component


Overload 2: Get the X (first) component

y(*args)

Overload 1: Get the Y (second) component


Overload 2: Get the Y (second) component

flipped()
dot(*args)
cross(other)

Get the cross product with another vector

__len__()
__iadd__(*args)
__add__(*args)
__isub__(*args)
__sub__(*args)
__imul__(*args)
__mul__(*args)
__itruediv__(*args)
__truediv__(*args)
__getitem__(index: int)
__setitem__(index: int, val)
as_list() list

convert to a python list

__str__() str

Return str(self).

class tissue_forge.dVector3(*args)

A 3D vector with double elements

static xAxis(*args, **kwargs)
static yAxis(*args, **kwargs)
static zAxis(*args, **kwargs)
static xScale(scale)
static yScale(scale)
static zScale(scale)
x(*args)

Overload 1: Get the X (first) component


Overload 2: Get the X (first) component

y(*args)

Overload 1: Get the Y (second) component


Overload 2: Get the Y (second) component

z(*args)

Overload 1: Get the Z (third) component


Overload 2: Get the Z (third) component

r(*args)

Overload 1: Get the red (first) component


Overload 2: Get the red (first) component

g(*args)

Overload 1: Get the green (second) component


Overload 2: Get the green (second) component

b(*args)

Overload 1: Get the blue (third) component


Overload 2: Get the blue (third) component

xy()
flipped()
dot(*args)
cross(other)

Get the cross product with another vector

angle(other)

angle made with another vector

__len__()
__iadd__(*args)
__add__(*args)
__isub__(*args)
__sub__(*args)
__imul__(*args)
__mul__(*args)
__itruediv__(*args)
__truediv__(*args)
length()

length of vector

normalized()

vector normalized

resized(length)

resize be a length

projected(other)

project onto another vector

projectedOntoNormalized(other)

project onto a normalized vector

distance(line_start_pt, line_end_pt)

distance from a line defined by two points

__getitem__(index: int)
__setitem__(index: int, val)
as_list() list

convert to a python list

__str__() str

Return str(self).

class tissue_forge.fVector3(*args)

A 3D vector with float elements

static xAxis(*args, **kwargs)
static yAxis(*args, **kwargs)
static zAxis(*args, **kwargs)
static xScale(scale)
static yScale(scale)
static zScale(scale)
x(*args)

Overload 1: Get the X (first) component


Overload 2: Get the X (first) component

y(*args)

Overload 1: Get the Y (second) component


Overload 2: Get the Y (second) component

z(*args)

Overload 1: Get the Z (third) component


Overload 2: Get the Z (third) component

r(*args)

Overload 1: Get the red (first) component


Overload 2: Get the red (first) component

g(*args)

Overload 1: Get the green (second) component


Overload 2: Get the green (second) component

b(*args)

Overload 1: Get the blue (third) component


Overload 2: Get the blue (third) component

xy()
flipped()
dot(*args)
cross(other)

Get the cross product with another vector

angle(other)

angle made with another vector

__len__()
__iadd__(*args)
__add__(*args)
__isub__(*args)
__sub__(*args)
__imul__(*args)
__mul__(*args)
__itruediv__(*args)
__truediv__(*args)
length()

length of vector

normalized()

vector normalized

resized(length)

resize be a length

projected(other)

project onto another vector

projectedOntoNormalized(other)

project onto a normalized vector

distance(line_start_pt, line_end_pt)

distance from a line defined by two points

__getitem__(index: int)
__setitem__(index: int, val)
as_list() list

convert to a python list

__str__() str

Return str(self).

class tissue_forge.iVector3(*args)

A 3D vector with int elements

static xAxis(*args, **kwargs)
static yAxis(*args, **kwargs)
static zAxis(*args, **kwargs)
static xScale(scale)
static yScale(scale)
static zScale(scale)
x(*args)

Overload 1: Get the X (first) component


Overload 2: Get the X (first) component

y(*args)

Overload 1: Get the Y (second) component


Overload 2: Get the Y (second) component

z(*args)

Overload 1: Get the Z (third) component


Overload 2: Get the Z (third) component

r(*args)

Overload 1: Get the red (first) component


Overload 2: Get the red (first) component

g(*args)

Overload 1: Get the green (second) component


Overload 2: Get the green (second) component

b(*args)

Overload 1: Get the blue (third) component


Overload 2: Get the blue (third) component

xy(*args)

Overload 1: Get the x-y (first-second) components


Overload 2: Get the x-y (first-second) components

flipped()
dot(*args)
cross(other)

Get the cross product with another vector

__len__()
__iadd__(*args)
__add__(*args)
__isub__(*args)
__sub__(*args)
__imul__(*args)
__mul__(*args)
__itruediv__(*args)
__truediv__(*args)
__getitem__(index: int)
__setitem__(index: int, val)
as_list() list

convert to a python list

__str__() str

Return str(self).

class tissue_forge.dVector4(*args)

A 4D vector with double elements

x(*args)

Overload 1: Get the X (first) component


Overload 2: Get the X (first) component

y(*args)

Overload 1: Get the Y (second) component


Overload 2: Get the Y (second) component

z(*args)

Overload 1: Get the Z (third) component


Overload 2: Get the Z (third) component

w(*args)

Overload 1: Get the W (fourth) component


Overload 2: Get the W (fourth) component

r(*args)

Overload 1: Get the red (first) component


Overload 2: Get the red (first) component

g(*args)

Overload 1: Get the green (second) component


Overload 2: Get the green (second) component

b(*args)

Overload 1: Get the blue (third) component


Overload 2: Get the blue (third) component

a(*args)

Overload 1: Get the alpha (fourth) component


Overload 2: Get the alpha (fourth) component

xyz()
rgb(*args)

Overload 1: Get the red-green-blue (first-second-third) components


Overload 2: Get the red-green-blue (first-second-third) components

xy(*args)

Overload 1: Get the x-y (first-second) components


Overload 2: Get the x-y (first-second) components

flipped()
dot(*args)
angle(other)

angle made with another vector

__len__()
__iadd__(*args)
__add__(*args)
__isub__(*args)
__sub__(*args)
__imul__(*args)
__mul__(*args)
__itruediv__(*args)
__truediv__(*args)
length()

length of vector

normalized()

vector normalized

resized(length)

resize be a length

projected(other)

project onto another vector

projectedOntoNormalized(other)

project onto a normalized vector

distance(point)

distance from a point

distanceScaled(point)

scaled distance from a point

classmethod planeEquation(*args)

get a plane equation

__getitem__(index: int)
__setitem__(index: int, val)
as_list() list

convert to a python list

__str__() str

Return str(self).

class tissue_forge.fVector4(*args)

A 4D vector with float elements

x(*args)

Overload 1: Get the X (first) component


Overload 2: Get the X (first) component

y(*args)

Overload 1: Get the Y (second) component


Overload 2: Get the Y (second) component

z(*args)

Overload 1: Get the Z (third) component


Overload 2: Get the Z (third) component

w(*args)

Overload 1: Get the W (fourth) component


Overload 2: Get the W (fourth) component

r(*args)

Overload 1: Get the red (first) component


Overload 2: Get the red (first) component

g(*args)

Overload 1: Get the green (second) component


Overload 2: Get the green (second) component

b(*args)

Overload 1: Get the blue (third) component


Overload 2: Get the blue (third) component

a(*args)

Overload 1: Get the alpha (fourth) component


Overload 2: Get the alpha (fourth) component

xyz()
rgb(*args)

Overload 1: Get the red-green-blue (first-second-third) components


Overload 2: Get the red-green-blue (first-second-third) components

xy(*args)

Overload 1: Get the x-y (first-second) components


Overload 2: Get the x-y (first-second) components

flipped()
dot(*args)
angle(other)

angle made with another vector

__len__()
__iadd__(*args)
__add__(*args)
__isub__(*args)
__sub__(*args)
__imul__(*args)
__mul__(*args)
__itruediv__(*args)
__truediv__(*args)
length()

length of vector

normalized()

vector normalized

resized(length)

resize be a length

projected(other)

project onto another vector

projectedOntoNormalized(other)

project onto a normalized vector

distance(point)

distance from a point

distanceScaled(point)

scaled distance from a point

classmethod planeEquation(*args)

get a plane equation

__getitem__(index: int)
__setitem__(index: int, val)
as_list() list

convert to a python list

__str__() str

Return str(self).

class tissue_forge.iVector4(*args)

A 4D vector with int elements

x(*args)

Overload 1: Get the X (first) component


Overload 2: Get the X (first) component

y(*args)

Overload 1: Get the Y (second) component


Overload 2: Get the Y (second) component

z(*args)

Overload 1: Get the Z (third) component


Overload 2: Get the Z (third) component

w(*args)

Overload 1: Get the W (fourth) component


Overload 2: Get the W (fourth) component

r(*args)

Overload 1: Get the red (first) component


Overload 2: Get the red (first) component

g(*args)

Overload 1: Get the green (second) component


Overload 2: Get the green (second) component

b(*args)

Overload 1: Get the blue (third) component


Overload 2: Get the blue (third) component

a(*args)

Overload 1: Get the alpha (fourth) component


Overload 2: Get the alpha (fourth) component

xyz(*args)

Overload 1: Get the x-y-z (first-second-third) components


Overload 2: Get the x-y-z (first-second-third) components

rgb(*args)

Overload 1: Get the red-green-blue (first-second-third) components


Overload 2: Get the red-green-blue (first-second-third) components

xy(*args)

Overload 1: Get the x-y (first-second) components


Overload 2: Get the x-y (first-second) components

flipped()
dot(*args)
__len__()
__iadd__(*args)
__add__(*args)
__isub__(*args)
__sub__(*args)
__imul__(*args)
__mul__(*args)
__itruediv__(*args)
__truediv__(*args)
__getitem__(index: int)
__setitem__(index: int, val)
as_list() list

convert to a python list

__str__() str

Return str(self).

class tissue_forge.dMatrix3(*args)

A 3x3 square matrix with double elements

static rotation(angle)

Initialize a rotation matrix

static shearingX(amount)

Initialize a shearing matrix along the X (first) direction

static shearingY(amount)

Initialize a shearing matrix along the Y (second) direction

isRigidTransformation()

Test whether the matrix is a rigid transformation

invertedRigid()

Get the inverted rigid transformation. Must be a rigid transformation.

__neg__()
__iadd__(other)
__add__(other)
__isub__(other)
__sub__(other)
__imul__(number)
__mul__(*args)
__itruediv__(*args)
__truediv__(*args)
flippedCols()
flippedRows()
row(row)
__mul__(*args)
transposed()
diagonal()
inverted()
invertedOrthogonal()
__len__()
__getitem__(index: int)
__setitem__(index: int, val)
as_lists() list

convert to a list of python lists

__str__() str

Return str(self).

class tissue_forge.fMatrix3(*args)

A 3x3 square matrix with float elements

static rotation(angle)

Initialize a rotation matrix

static shearingX(amount)

Initialize a shearing matrix along the X (first) direction

static shearingY(amount)

Initialize a shearing matrix along the Y (second) direction

isRigidTransformation()

Test whether the matrix is a rigid transformation

invertedRigid()

Get the inverted rigid transformation. Must be a rigid transformation.

__neg__()
__iadd__(other)
__add__(other)
__isub__(other)
__sub__(other)
__imul__(number)
__mul__(*args)
__itruediv__(*args)
__truediv__(*args)
flippedCols()
flippedRows()
row(row)
__mul__(*args)
transposed()
diagonal()
inverted()
invertedOrthogonal()
__len__()
__getitem__(index: int)
__setitem__(index: int, val)
as_lists() list

convert to a list of python lists

__str__() str

Return str(self).

class tissue_forge.dMatrix4(*args)

A 4x4 square matrix with double elements

static rotationX(angle)

Initialize a rotation matrix about the X (first) axis

static rotationY(angle)

Initialize a rotation matrix about the Y (second) axis

static rotationZ(angle)

Initialize a rotation matrix about the Z (third) axis

static reflection(normal)

Initialize a reflection matrix about a plane using the normalized plane normal

static shearingXY(amountX, amountY)

Initialize a shearing matrix about the X (first) and Y (second) axes

static shearingXZ(amountX, amountZ)

Initialize a shearing matrix about the X (first) and Z (third) axes

static shearingYZ(amountY, amountZ)

Initialize a shearing matrix about the Y (second) and Z (third) axes

static orthographicProjection(size, near, far)

Initialize an orthographic projection matrix

Parameters:
  • size (TissueForge::types::TVector2< double >) – size of the view

  • near (float) – distance to near clipping plane

  • far (float) – distance for far clipping plane

static perspectiveProjection(*args)

Overload 1:

Initialize an perspective projection matrix

Parameters:
  • size (TissueForge::types::TVector2< double >) – size of the near clipping plane

  • near (float) – distance to near clipping plane

  • far (float) – distance for far clipping plane


Overload 2:

Initialize a perspective projection matrix

Parameters:
  • fov (float) – horizontal angle of the field of view

  • aspectRatio (float) – horizontal:vertical field of view aspect ratio

  • near (float) – distance to near clipping plane

  • far (float) – distance for far clipping plane


Overload 3:

Initialize a perspective projection matrix

Parameters:
  • bottomLeft (TissueForge::types::TVector2< double >) – bottom-left point of field of view

  • topRight (TissueForge::types::TVector2< double >) – top-right point of field of view

  • near (float) – distance to near clipping plane

  • far (float) – distance for far clipping plane

static lookAt(eye, target, up)

Initialize a matrix oriented towards a point

Parameters:
  • eye (TissueForge::types::TVector3< double >) – location of view

  • target (TissueForge::types::TVector3< double >) – location of target point

  • up (TissueForge::types::TVector3< double >) – upward-normal of view

isRigidTransformation()

Test whether the matrix is a rigid transformation

rotationScaling()

Get the rotation and scaling matrix

rotationShear()

Get the rotation and shear matrix

rotation(*args)

Overload 1: Initialize a rotation matrix from a rotation angle and normalized axis of rotation


Overload 2: Get the rotation matrix

rotationNormalized()

Get the normalized rotation matrix

scalingSquared()

Get the squared scaling vector

scaling(*args)

Overload 1: Initialize a scaling matrix from a scaling vector


Overload 2: Get the scaling vector

uniformScalingSquared()

Get the uniform squared scaling vector

uniformScaling()

Get the uniform scaling vector

normalMatrix()

Get the normal matrix

right(*args)

Overload 1: Get the rightward-pointing vector


Overload 2: Get the rightward-pointing vector

up(*args)

Overload 1: Get the upward-pointing vector


Overload 2: Get the upward-pointing vector

backward(*args)

Overload 1: Get the backward-pointing vector


Overload 2: Get the backward-pointing vector

translation(*args)

Overload 1: Initialize a translation matrix from a translation vector


Overload 2: Get the translation vector


Overload 3: Get the translation vector

invertedRigid()

Get the inverted rigid transformation matrix. Must be a rigid transformation matrix.

transformVector(vector)

Transform a vector

transformPoint(vector)

Transform a point

__neg__()
__iadd__(other)
__add__(other)
__isub__(other)
__sub__(other)
__imul__(number)
__itruediv__(*args)
__truediv__(*args)
flippedCols()
flippedRows()
row(row)
__mul__(*args)
transposed()
diagonal()
inverted()
invertedOrthogonal()
__len__()
__getitem__(index: int)
__setitem__(index: int, val)
as_lists() list

convert to a list of python lists

__str__() str

Return str(self).

class tissue_forge.fMatrix4(*args)

A 4x4 square matrix with float elements

static rotationX(angle)

Initialize a rotation matrix about the X (first) axis

static rotationY(angle)

Initialize a rotation matrix about the Y (second) axis

static rotationZ(angle)

Initialize a rotation matrix about the Z (third) axis

static reflection(normal)

Initialize a reflection matrix about a plane using the normalized plane normal

static shearingXY(amountX, amountY)

Initialize a shearing matrix about the X (first) and Y (second) axes

static shearingXZ(amountX, amountZ)

Initialize a shearing matrix about the X (first) and Z (third) axes

static shearingYZ(amountY, amountZ)

Initialize a shearing matrix about the Y (second) and Z (third) axes

static orthographicProjection(size, near, far)

Initialize an orthographic projection matrix

Parameters:
  • size (TissueForge::types::TVector2< float >) – size of the view

  • near (float) – distance to near clipping plane

  • far (float) – distance for far clipping plane

static perspectiveProjection(*args)

Overload 1:

Initialize an perspective projection matrix

Parameters:
  • size (TissueForge::types::TVector2< float >) – size of the near clipping plane

  • near (float) – distance to near clipping plane

  • far (float) – distance for far clipping plane


Overload 2:

Initialize a perspective projection matrix

Parameters:
  • fov (float) – horizontal angle of the field of view

  • aspectRatio (float) – horizontal:vertical field of view aspect ratio

  • near (float) – distance to near clipping plane

  • far (float) – distance for far clipping plane


Overload 3:

Initialize a perspective projection matrix

Parameters:
  • bottomLeft (TissueForge::types::TVector2< float >) – bottom-left point of field of view

  • topRight (TissueForge::types::TVector2< float >) – top-right point of field of view

  • near (float) – distance to near clipping plane

  • far (float) – distance for far clipping plane

static lookAt(eye, target, up)

Initialize a matrix oriented towards a point

Parameters:
  • eye (TissueForge::types::TVector3< float >) – location of view

  • target (TissueForge::types::TVector3< float >) – location of target point

  • up (TissueForge::types::TVector3< float >) – upward-normal of view

isRigidTransformation()

Test whether the matrix is a rigid transformation

rotationScaling()

Get the rotation and scaling matrix

rotationShear()

Get the rotation and shear matrix

rotation(*args)

Overload 1: Initialize a rotation matrix from a rotation angle and normalized axis of rotation


Overload 2: Get the rotation matrix

rotationNormalized()

Get the normalized rotation matrix

scalingSquared()

Get the squared scaling vector

scaling(*args)

Overload 1: Initialize a scaling matrix from a scaling vector


Overload 2: Get the scaling vector

uniformScalingSquared()

Get the uniform squared scaling vector

uniformScaling()

Get the uniform scaling vector

normalMatrix()

Get the normal matrix

right(*args)

Overload 1: Get the rightward-pointing vector


Overload 2: Get the rightward-pointing vector

up(*args)

Overload 1: Get the upward-pointing vector


Overload 2: Get the upward-pointing vector

backward(*args)

Overload 1: Get the backward-pointing vector


Overload 2: Get the backward-pointing vector

translation(*args)

Overload 1: Initialize a translation matrix from a translation vector


Overload 2: Get the translation vector


Overload 3: Get the translation vector

invertedRigid()

Get the inverted rigid transformation matrix. Must be a rigid transformation matrix.

transformVector(vector)

Transform a vector

transformPoint(vector)

Transform a point

__neg__()
__iadd__(other)
__add__(other)
__isub__(other)
__sub__(other)
__imul__(number)
__itruediv__(*args)
__truediv__(*args)
flippedCols()
flippedRows()
row(row)
__mul__(*args)
transposed()
diagonal()
inverted()
invertedOrthogonal()
__len__()
__getitem__(index: int)
__setitem__(index: int, val)
as_lists() list

convert to a list of python lists

__str__() str

Return str(self).

class tissue_forge.dQuaternion(*args)

A quaternion with double elements

static rotation(angle, normalizedAxis)

Initialize from a rotation angle and normalized axis of rotation

static fromMatrix(matrix)

Initialize from an orthogonal rotation matrix

data(*args)

Overload 1: Get the underlying array


Overload 2: Get the underlying array

__eq__(other)

Return self==value.

__ne__(other)

Return self!=value.

isNormalized()

Test whether the quaternion is normalized

vector()

Get the 3-component vector

scalar()

Get the scalar

angle(*args)

Overload 1: Get the angle. Quaternion should be normalized.


Overload 2: Get the angle

axis()

Get the rotation axis. Quaternion should be normalized.

toMatrix()

Get the rotation matrix

toEuler()

Get the Euler angles

__neg__()
__iadd__(other)
__add__(other)
__isub__(other)
__sub__(other)
__imul__(scalar)
__itruediv__(*args)
__truediv__(*args)
__mul__(*args)
dot()

Get the squared length

length()

Get the length

normalized()

Get the normalized quaternion

conjugated()

Get the conjugated quaternion

inverted()

Get the inverted quaternion

invertedNormalized()

Get the inverted and normalized quaternion

transformVector(vector)

Transform a vector

transformVectorNormalized(vector)

Transform a normalized vector

__getitem__(index: int)
__setitem__(index: int, val)
as_list() list

convert to a python list

__str__() str

Return str(self).

class tissue_forge.fQuaternion(*args)

A quaternion with float elements

static rotation(angle, normalizedAxis)

Initialize from a rotation angle and normalized axis of rotation

static fromMatrix(matrix)

Initialize from an orthogonal rotation matrix

data(*args)

Overload 1: Get the underlying array


Overload 2: Get the underlying array

__eq__(other)

Return self==value.

__ne__(other)

Return self!=value.

isNormalized()

Test whether the quaternion is normalized

vector()

Get the 3-component vector

scalar()

Get the scalar

angle(*args)

Overload 1: Get the angle. Quaternion should be normalized.


Overload 2: Get the angle

axis()

Get the rotation axis. Quaternion should be normalized.

toMatrix()

Get the rotation matrix

toEuler()

Get the Euler angles

__neg__()
__iadd__(other)
__add__(other)
__isub__(other)
__sub__(other)
__imul__(scalar)
__itruediv__(*args)
__truediv__(*args)
__mul__(*args)
dot()

Get the squared length

length()

Get the length

normalized()

Get the normalized quaternion

conjugated()

Get the conjugated quaternion

inverted()

Get the inverted quaternion

invertedNormalized()

Get the inverted and normalized quaternion

transformVector(vector)

Transform a vector

transformVectorNormalized(vector)

Transform a normalized vector

__getitem__(index: int)
__setitem__(index: int, val)
as_list() list

convert to a python list

__str__() str

Return str(self).

tissue_forge.FVector2

alias of fVector2

tissue_forge.FVector3

alias of fVector3

tissue_forge.FVector4

alias of fVector4

tissue_forge.FMatrix3

alias of fMatrix3

tissue_forge.FMatrix4

alias of fMatrix4

tissue_forge.FQuaternion

alias of fQuaternion

File I/O

tissue_forge.io.fromFile3DF(filePath)

Tissue Forge import/export interface

Load a 3D format file

Parameters:

filePath (string) – path of file

Return type:

ThreeDFStructure

Returns:

ThreeDFStructure* 3D format data container

tissue_forge.io.toFile3DF(format, filePath, pRefinements=0)

Export engine state to a 3D format file

Parameters:
  • format (string) – format of file

  • filePath (string) – path of file

  • pRefinements (int, optional) – mesh refinements applied when generating meshes

Return type:

int

Returns:

HRESULT

tissue_forge.io.toFile(saveFilePath)

Save a simulation to file

Parameters:

saveFilePath (string) – absolute path to file

Return type:

int

Returns:

HRESULT

tissue_forge.io.toString()

Return a simulation state as a JSON string

Return type:

string

Returns:

std::string

tissue_forge.io.mapImportParticleId(pId)

Get the id of a particle according to import data that corresponds to a particle id of current data.

Only valid between initialization and the first simulation step, after which the import summary data is purged.

Parameters:

pId (int) – id of particle in exported data

Return type:

int

Returns:

int >=0 if particle is found; -1 otherwise

tissue_forge.io.mapImportParticleTypeId(pId)

Get the id of a particle type according to import data that corresponds to a particle type id of current data.

Only valid between initialization and the first simulation step, after which the import summary data is purged.

Parameters:

pId (int) – id of particle type in exported data

Return type:

int

Returns:

int >=0 if particle type is found; -1 otherwise

class tissue_forge.io.ThreeDFRenderData
property color
class tissue_forge.io.ThreeDFStructure
property centroid: fVector3

Centroid of all constituent data

property vertices: vectorThreeDFVertexData_p

Constituent vertices

property edges: vectorThreeDFEdgeData_p

Constituent edges

property faces: vectorThreeDFFaceData_p

Constituent faces

property meshes: vectorThreeDFMeshData_p

Constituent meshes

property num_vertices: int

Number of constituent vertices

property num_edges: int

Number of constituent edges

property num_faces: int

Number of constituent faces

property num_meshes: int

Number of constituent meshes

property vRadiusDef

Default radius applied to vertices when generating meshes from point clouds

fromFile(filePath)

Load from file

Parameters:

filePath (string) – file absolute path

Return type:

int

Returns:

HRESULT

toFile(format, filePath)

Write to file

Parameters:
  • format (string) – output format of file

  • filePath (string) – file absolute path

Return type:

int

Returns:

HRESULT

flush()

Flush stucture. All scheduled processes are executed.

extend(s)

Extend a structure

Parameters:

s (ThreeDFStructure) – stucture to extend with

clear()

Clear all data of the structure

Return type:

int

Returns:

HRESULT

has(*args)

Overload 1:

Test whether a vertex is a constituent

Parameters:

v (ThreeDFVertexData) – vertex to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 2:

Test whether an edge is a constituent

Parameters:

e (ThreeDFEdgeData) – edge to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 3:

Test whether a face is a constituent

Parameters:

f (ThreeDFFaceData) – face to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 4:

Test whether a mesh is a constituent

Parameters:

m (ThreeDFMeshData) – mesh to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false

add(*args)

Overload 1:

Add a vertex

Parameters:

v (ThreeDFVertexData) – vertex to add


Overload 2:

Add an edge and all constituent data

Parameters:

e (ThreeDFEdgeData) – edge to add


Overload 3:

Add a face and all constituent data

Parameters:

f (ThreeDFFaceData) – face to add


Overload 4:

Add a mesh and all constituent data

Parameters:

m (ThreeDFMeshData) – mesh to add

remove(*args)

Overload 1:

Remove a vertex

Parameters:

v (ThreeDFVertexData) – vertex to remove


Overload 2:

Remove a edge and all constituent data

Parameters:

e (ThreeDFEdgeData) – edge to remove


Overload 3:

Remove a face and all constituent data

Parameters:

f (ThreeDFFaceData) – face to remove


Overload 4:

Remove a mesh and all constituent data

Parameters:

m (ThreeDFMeshData) – mesh to remove

translate(displacement)

Translate the structure by a displacement

Parameters:

displacement (FVector3) –

Return type:

int

Returns:

HRESULT

translateTo(position)

Translate the structure to a position

Parameters:

position (FVector3) –

Return type:

int

Returns:

HRESULT

rotateAt(rotMat, rotPt)

Rotate the structure about a point

Parameters:
  • rotMat (FMatrix3) –

  • rotPt (FVector3) –

Return type:

int

Returns:

HRESULT

rotate(rotMat)

Rotate the structure about its centroid

Parameters:

rotMat (FMatrix3) –

Return type:

int

Returns:

HRESULT

scaleFrom(*args)

Overload 1:

Scale the structure about a point

Parameters:
  • scales (FVector3) –

  • scalePt (FVector3) –

Return type:

int

Returns:

HRESULT


Overload 2:

Scale the structure uniformly about a point

Parameters:
  • scale (float) –

  • scalePt (FVector3) –

Return type:

int

Returns:

HRESULT

scale(*args)

Overload 1:

Scale the structure about its centroid

Parameters:

scales (FVector3) –

Return type:

int

Returns:

HRESULT


Overload 2:

Scale the structure uniformly about its centroid

Parameters:

scale (float) –

Return type:

int

Returns:

HRESULT

class tissue_forge.io.ThreeDFMeshData
property structure

Parent structure

property id

ID, if any. Unique to its structure and type

property name

Mesh name

property renderData

Rendering data

property vertices: vectorThreeDFVertexData_p

Constituent vertices

property edges: vectorThreeDFEdgeData_p

Constituent edges

property faces: vectorThreeDFFaceData_p

Constituent faces

property num_vertices: int

Number of constituent vertices

property num_edges: int

Number of constituent edges

property num_faces: int

Number of constituent faces

property centroid: fVector3

Centroid of all constituent data

has(*args)

Overload 1:

Test whether a vertex is a constituent

Parameters:

v (ThreeDFVertexData) – vertex to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 2:

Test whether an edge is a constituent

Parameters:

e (ThreeDFEdgeData) – edge to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 3:

Test whether a face is a constituent

Parameters:

f (ThreeDFFaceData) – face to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false

_in(s)

Test whether in a structure

Parameters:

s (ThreeDFStructure) – structure to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false

is_in(*args, **kwargs) bool

Alias of :meth:_in

translate(displacement)

Translate the mesh by a displacement

Parameters:

displacement (FVector3) –

Return type:

int

Returns:

HRESULT

translateTo(position)

Translate the mesh to a position

Parameters:

position (FVector3) –

Return type:

int

Returns:

HRESULT

rotateAt(rotMat, rotPt)

Rotate the mesh about a point

Parameters:
  • rotMat (FMatrix3) –

  • rotPt (FVector3) –

Return type:

int

Returns:

HRESULT

rotate(rotMat)

Rotate the mesh about its centroid

Parameters:

rotMat (FMatrix3) –

Return type:

int

Returns:

HRESULT

scaleFrom(*args)

Overload 1:

Scale the mesh about a point

Parameters:
  • scales (FVector3) –

  • scalePt (FVector3) –

Return type:

int

Returns:

HRESULT


Overload 2:

Scale the mesh uniformly about a point

Parameters:
  • scale (float) –

  • scalePt (FVector3) –

Return type:

int

Returns:

HRESULT

scale(*args)

Overload 1:

Scale the mesh about its centroid

Parameters:

scales (FVector3) –

Return type:

int

Returns:

HRESULT


Overload 2:

Scale the mesh uniformly about its centroid

Parameters:

scale (float) –

Return type:

int

Returns:

HRESULT

class tissue_forge.io.ThreeDFFaceData
property structure

Parent structure

property normal

Face normal

property id

ID, if any. Unique to its structure and type

property vertices: vectorThreeDFVertexData_p

Constituent vertices

property edges: vectorThreeDFEdgeData_p

Constituent edges

property meshes: vectorThreeDFMeshData_p

Parent meshes

property num_vertices: int

Number of constituent vertices

property num_edges: int

Number of constituent edges

property num_meshes: int

Number of parent meshes

has(*args)

Overload 1:

Test whether a vertex is a constituent

Parameters:

v (ThreeDFVertexData) – vertex to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 2:

Test whether an edge is a constituent

Parameters:

e (ThreeDFEdgeData) – edge to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false

_in(*args)

Overload 1:

Test whether in a mesh

Parameters:

m (ThreeDFMeshData) – mesh to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 2:

Test whether in a structure

Parameters:

s (ThreeDFStructure) – structure to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false

is_in(*args, **kwargs) bool

Alias of :meth:_in

class tissue_forge.io.ThreeDFEdgeData(_va, _vb)
property structure

Parent structure

property id

ID, if any. Unique to its structure and type

property vertices: vectorThreeDFVertexData_p

Constituent vertices

property faces: vectorThreeDFFaceData_p

Constituent faces

property meshes: vectorThreeDFMeshData_p

Parent meshes

property num_vertices: int

Number of constituent vertices

property num_faces: int

Number of parent faces

property num_meshes: int

Number of parent meshes

has(v)

Test whether a vertex is a constituent

Parameters:

v (ThreeDFVertexData) – vertex to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false

_in(*args)

Overload 1:

Test whether in a face

Parameters:

f (ThreeDFFaceData) – face to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 2:

Test whether in a mesh

Parameters:

m (ThreeDFMeshData) – mesh to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 3:

Test whether in a structure

Parameters:

s (ThreeDFStructure) – structure to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false

is_in(*args, **kwargs) bool

Alias of :meth:_in

class tissue_forge.io.ThreeDFVertexData(_position, _structure=None)
property structure

Parent structure

property position

Global position

property id

ID, if any. Unique to its structure and type

property edges: vectorThreeDFEdgeData_p

Parent edges

property faces: vectorThreeDFFaceData_p

Parent faces

property meshes: vectorThreeDFMeshData_p

Parent meshes

property num_edges: int

Number of parent edges

property num_faces: int

Number of parent faces

property num_meshes: int

Number of parent meshes

_in(*args)

Overload 1:

Test whether in an edge

Parameters:

e (ThreeDFEdgeData) – edge to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 2:

Test whether in a face

Parameters:

f (ThreeDFFaceData) – face to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 3:

Test whether in a mesh

Parameters:

m (ThreeDFMeshData) – mesh to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false


Overload 4:

Test whether in a structure

Parameters:

s (ThreeDFStructure) – structure to test

Return type:

boolean

Returns:

true

Return type:

boolean

Returns:

false

is_in(*args, **kwargs) bool

Alias of :meth:_in

GPU-Accelerated Modules

Note

This section of the Tissue Forge API is only available in CUDA-supported installations.