About the Python Api

The Python API is build upon the C++ library using pybind11. This API does not provide as much control over the simulations as using the C++ library directly, however it retains the majority of the functionality, has a lower barrier to entry and, it is more readable. If you are looking to utilize pd3, this API is recommended.

If using the pypi module, or compiling with the dynamic flag. Note that the if you are unsure, the type of pd^3 compilation can be verified with the scripts/

Examples

Creating and visualizing a dislocation microstrcture.

import numpy as np
import pd3
study = pd3.Study()

# Define our burgers vector for the cubic system.
b100 = pd3.Burgers((1, 0, 0))
plane = pd3.Miller((0, 1, 0))

# Place a node at the origin, and other nodes such that we can have both
# edge and screw representation.
origin_node = study.create_node(0, 0, 0)
screw_direction_node = study.create_node(100, 0, 0)
edge_direction_node = study.create_node(0, 0, -100)

# Connect the nodes into a triangle using the prescribed burgers and plane.
study.connect(origin_node, screw_direction_node, b100, plane)
study.connect(screw_direction_node, edge_direction_node, b100, plane)
study.connect(edge_direction_node, origin_node, b100, plane)
# Alternatively we could have done
# study.line(b100, plane).start(origin_node).connect(100, 0, 0).connect(0, 0, -100).connect(origin_node)

# We can then vizulize this construction using [pd3_plot](https://github.com/cemel-jhu/pd3_plot)
from pd3_plot import Plotter as pd3p
plotter = pd3p(study.export_protobuf())
plotter.plot_2D(x_axis=(1, 0, 0),
                y_axis=(0, 0, 1))

Running a dislocation microstrcture with boundary conditions.

# Load pd^3, np, create study etc...
# Certain attributes like the stress state are easily configured.
study.stress = 1e-11 * np.array([[0, 1, 0], [1, 0, 0], [0, 0, 0]])

# We can set a function to enforce study conditions on every step.
def increase_stress(state: pd3.State):
    study.stress = study.stress * 1.001
    return pd3.Ok()
study.study_condition = increase_stress

# Finally, we can run the simulation
study.run()

Restarting a previous simulation, and determining run conditions.

# Load pd^3, np, create study etc...
# Note, this only works on pd^3 files, but pull requests accepted.
study.load_file("myfile.pbtxt")