Package: pvtrace
Optical ray tracing for luminescent materials and spectral converter photovoltaic devicesRay-tracing luminescent solar concentratorspvtraceis a statistical photon path tracer written in Python. Rays are followed through a 3D scene and their interactions with objects are recorded to build up statistical information about energy flow.This is useful in photovoltaics and non-imaging optics where the goal is to design systems which efficiently transport light to target locations.One of its key features is the ability to simulate re-absorption in luminescent materials. For example, like in devices like Luminescent Solar Concentrators (LSCs).A basic LSC can be simulated and visualised in five lines of code,frompvtraceimport*lsc=LSC((5.0,5.0,1.0))# size in cmlsc.show()# open visualiserlsc.simulate(100)# emit 100 rayslsc.report()# print reportThis script will render the ray-tracing in real time,pvtrace has been validate against three other luminescent concentrator codes. For full details seeValidation.ipynbnotebookInstallMacOS using pyenvOn MacOSpvtracecan be installed easily usingpyenv, thepipcommand andhomebrew. First installhomebrew, then installspatialindexfor the RTree dependency,brew install spatialindexNext, create a clean virtual environment for pvtracepyenv install 3.7.8
pyenv virtualenv 3.7.8 pvtrace-env
pyenv activate pvtrace-env
pip install pvtraceLinux and Windows using CondaOn Linux and Windows you must use conda to create the python environment. Optionally you can also use this method on MacOS too if you prefer conda over pyenv.conda create --name pvtrace-env python=3.7.8
conda activate pvtrace-env
conda install Rtree
pip install pvtraceRun the example script and notebooksDownload thehello_world.pyexample script either manually or usingcurl,# Download example script
curl https://raw.githubusercontent.com/danieljfarrell/pvtrace/master/examples/hello_world.py > hello_world.pyNow active your python environment!If you installed usingpyenvdo the following,pyenv local pvtrace-envIf you are usingcondato this,conda activate pvtrace-envNow start the meshcat server with the command,meshcat-serverThis will print information like,zmq_url=tcp://127.0.0.1:6000
web_url=http://127.0.0.1:7000/static/Open a new terminal window and again activate your pvtrace-env.Openhello_world.pyand make sure the line below haszmq_urlof your meshcat-server,# Change zmq_url here to be the address of your meshcat-server!
renderer = MeshcatRenderer(
    zmq_url="tcp://127.0.0.1:6000", wireframe=True, open_browser=True
)You can now run pvtrace scripts! Run this following command,python hello_world.pyAlso take a look at the online Jupyter notebook tutorial series which provide an overview of pvtrace and examples,Quick Start.ipynb, an interactive ray-tracing tutorial (download an run locally)Materials.ipynb, include physical properties with materialsLights.ipynb, place photon sources in the scene and customise their propertiesNodes.ipynbtranslate and rotate scene objects with nodesGeometry.ipynbdefine the shapes of objects in your sceneCoatings.ipynbintroduce custom reflections with coatingsDownload and run these notebooks locally for a more interactive experience, but first install jupyter,pip install jupyteror with conda,conda install jupyterThen launch the jupyter notebook,jupyter notebookFeaturesRay optics simulationspvtracesupports 3D ray optics simulations shapes,boxspherecylindermeshThe optical properties of each shape can be customised,refractive indexabsorption coefficientscattering coefficientemission lineshapequantum yieldsurface reflectionsurface scatteringHigh and low-level APIpvtracehas a high-level API for handling common problems with LSCs and a low-level API where objects can be positioned in a 3D scene and optical properties customised.For example, a script using the low-level API to ray trace this glass sphere is below,importtimeimportsysimportfunctoolsimportnumpyasnpfrompvtraceimport*# World node contains all objectsworld=Node(name="world (air)",geometry=Sphere(radius=10.0,material=Material(refractive_index=1.0),))# The glass spheresphere=Node(name="sphere (glass)",geometry=Sphere(radius=1.0,material=Material(refractive_index=1.5),),parent=world)sphere.location=(0,0,2)# The source of rayslight=Node(name="Light (555nm)",light=Light(direction=functools.partial(cone,np.pi/8)),parent=world)# Render and ray-tracerenderer=MeshcatRenderer(wireframe=True,open_browser=True)scene=Scene(world)renderer.render(scene)forrayinscene.emit(100):steps=photon_tracer.follow(scene,ray)path,events=zip(*steps)renderer.add_ray_path(path)time.sleep(0.1)# Wait for Ctrl-C to terminate the script; keep the window openprint("Ctrl-C to close")whileTrue:try:time.sleep(.3)exceptKeyboardInterrupt:sys.exit()Scene Graphpvtraceis designed in layers each with as limited scope as possible.SceneGraph data structure of node and the thing that is ray-traced.NodeProvides a coordinate system, can be nested inside one another, perform arbitrary rotation and translation transformations.GeometryAttached to nodes to define different shapes (Sphere, Box, Cylinder, Mesh) and handles all ray intersections.MaterialAttached to geometry objects to assign physical properties to shapes such as refractive index.SurfaceHandles details of interaction between material surfaces and a customisation point for simulation of wavelength selective coatings.ComponentsSpecifies optical properties of the geometries volume, absorption coefficient, scattering coefficient, quantum yield, emission spectrum.Ray-tracing engineThe algorithm which spawns rays, computes intersections, samples probabilities and traverses the rays through the scene.Ray-tracing engineCurrentlypvtracesupports only one ray-tracing engine: a photon path tracer. This is physically accurate, down to treating individual absorption and emission events, but is slow because the problem cannot be vectorised as each ray is followed individually.DocumentationInteractive Jupyter notebooks are inexamples directory, download and take a look, although they can be viewed online.ContributingPlease use the githubissuetracker for bug fixes, suggestions, or support questions.If you are considering contributing to pvtrace, first fork the project. This will make it easier to include your contributions using pull requests.Creating a development environmentFirst create a new development environment usingMacOS instructionsorLinux and Windows instructions, but do not install pvtrace using pip! You will need to clone your own copy of the source code in the following steps.Use the GitHub fork button to make your own fork of the project. This will make it easy to include your changes in pvtrace using a pull request.Follow the steps below to clone and install the development dependencies# Pull from your forkgitclonehttps://github.com/<yourusername>/pvtrace.git# Get development dependenciespipinstall-rpvtrace/requirements_dev.txt# Add local `pvtrace` directory to known packagespipinstall-epvtrace# Run units testspytestpvtrace/tests# Run an examplepythonpvtrace/examples/hello_world.pyYou should now be able to edit the source code and simply run scripts directly without the need to reinstall anything.Unit testsPlease add or modify an existing unit tests in thepvtrace/testsdirectory if you are adding new code. This will make it much easier to include your changes in the project.Pull requestsPull requests will be considered. Please make contact before doing a lot of work, to make sure that the changes will definitely be included in the main project.QuestionsYou can get in contact with me directly atdan@excitonlabs.comor raise an issue on the issue tracker.DependenciesBasic environment requires the following packages which will be installed withpipautomaticallypython >= 3.7.2numpypandastrimesh[easy]meshcat >= 0.0.16anytree