NanoParticleTools tools is a python module that facilitates monte carlo simulation of Upconverting Nanoparticles (UCNP) using RNMC and analysis/prediction using deep learning, detailed in the manuscript by Sivonxay et. al.

Using NanoParticleTools

NanoParticleTools provides functionality to generate inputs for running Monte Carlo Simulations on nanoparticles and analyzing outputs. Monte Carlo simulation uses NMPC within the RNMC package. While NanoParticleTools provides wrapper functions to run the C++ based simulator, RNMC must be installed to perform simulations.

Using only the machine learning capabilities within NanoParticleTools does not require the installation of RNMC

Installation

To install NanoParticleTools to a python environment, clone the repository and use one of the following commands from within the NanoParticleTools directory bash python setup.py develop or bash pip install .

Finally, install torch-scatter as follows. git clone https://github.com/rusty1s/pytorch_scatter.git pip install pytorch_scatter/ Note: This package is installed separately due to some installation issues. See: https://github.com/rusty1s/pytorchscatter/issues/265 and https://github.com/rusty1s/pytorchscatter/issues/424

Installation should take around 15 minutes on a normal desktop computer. NanoParticleTools can run on Python 3.10 and greater. The setup.py file includes pinned/constrained dependencies necessary for the installation.

Training and Using Machine Learning Models

The functionality to train and use deep learning models to predict UCNP emission intensity using NanoParticleTools is embedded here.

Within the demos folder, we have included Jupyter notebooks with demos for (1) training a deep learning model on pre-compiled datasets of RNMC trajectories, (2) loading pre-trained models and predicting emission intensity for an arbitrary UCNP design, and (3) loading pre-trained models and predicting emission intensity on the pre-compiled UCNP datasets.

Pre-compiled UCNP datasets (SUNSET) and pre-trained models can be downloaded from Figshare.

Running Simulations

An example of local execution can be seen below.

```python from NanoParticleTools.flows.flows import getnpmcflow from NanoParticleTools.inputs.nanoparticle import SphericalConstraint

constraints = [SphericalConstraint(20)] dopant_specifications = [(0, 0.1, 'Yb', 'Y'), (0, 0.02, 'Er', 'Y')]

npmcargs = {'npmccommand': , 'numsims':2, 'baseseed': 1000, 'threadcount': 8, 'simulationlength': 1000, } spectralkineticsargs = {'excitationpower': 1e12, 'excitationwavelength':980}

flow = getnpmcflow(constraints = constraints, dopantspecifications = dopantspecifications, dopingseed = 0, spectralkineticsargs = spectralkineticsargs, npmcargs = npmcargs, outputdir = './scratch') ```

```python from jobflow import run_locally from maggma.stores import MemoryStore from jobflow import JobStore

Store the output data locally in a MemoryStore

docsstore = MemoryStore() datastore = MemoryStore() store = JobStore(docsstore, additionalstores={'trajectories': data_store})

responses = runlocally(flow, store=store, ensuresuccess=True) ```

In this example, the target maggma.stores.MemoryStore used to collect output is volatile and will be lost if the Store is reinitialized or the python kernel is restarted. Therefore, one may opt to use a MongoDB server to save calculation output to ensure data persistence. To integrate a MongoDB, use a MongoStore instead of a MemoryStore. from maggma.stores.mongolike import MongoStore docs_store = MongoStore(<mongo credentials or URI here>) data_store = MongoStore(<mongo credentials or URI here>) Refer to the maggma Stores documentation for more information.

Running the Builder

After running simulations, you may wish to average the outputs of trajectories obtained from the same recipe (using different dopant and simulation seeds). We have included a maggma builder in NanoParticleTools to easily group documents and perform the averaging. More information on builders can be found in the maggma Builder documentation

An example of instantiating a builder is as follows: ``` from maggma.stores.mongolike import MongoStore

sourcestore = MongoStore(collectionname = "docsnpmc", ) targetstore = MongoStore(collectionname = "avgnpmc", )

builder = UCNPBuilder(sourcestore, targetstore, docsfilter={'data.simulationtime': {'$gte': 0.01}}, chunksize=4) `` Here, thesourcestoreis a maggma Store which contains the trajectory documents produced from the SimulationReplayer analysis of NPMC runs.targetstoreis the Store in which you would like your averaged documents to be populated to. Optional arguments include adocsfilter, which is a pymongo query to target specific documents.chunk_size` may also be specified and is dependent on the memory and speed of the machine executing the builder.

To execute the builder locally, use the builder.run() function. The builder may also be run in parallel or distributed mode, see the maggma "Running a Builder Pipeline" documentation

Contributing

If you wish to make changes to NanoParticle tools, it may be wise to install the package in development mode. After cloning the package, use the following command. bash python -m pip install -e . Modifications should now be reflected when you run any functions in NanoParticleTools.

pytest --cov-report term-missing --cov=src tests/ Further guidance on contributing via Pull Requests will be added in the near future.