Creating Simmate Apps¶
If you prefer learning from full examples, you can explore other apps built with Simmate at
Why create a Simmate App?¶
A custom Simmate app gives you the following features & advantages:
- Utilizing a custom database table to store workflow results
- Accessing workflows through the website interface
- Accessing workflows from other scripts (e.g., using the
- Organizing the code from larger projects into smaller files
- Sharing workflows within a team
- Allowing others to install your workflows (e.g., after publishing a new paper)
To achieve this, we need to organize our Python code in a specific format (i.e., there are rules for file naming and content).
Creating New App Files¶
To start a new app, navigate to your desired folder for code storage and run:
You will see the creation of a new folder named
my_new_project. Open it, you should find a series of new files:
my_new_project/ ├── pyproject.toml ├── README.md └── example_app ├── __init__.py ├── apps.py ├── models.py ├── tests.py ├── urls.py ├── views.py └── workflows.py
Note the presence of a folder named
example_app. This is where your code will reside. You can create as many app folders as needed, but this guide will focus on a single app.
Naming Your Project and App¶
Once you've chosen a name, stick with it. Altering your project or app name post-installation can result in
Naming the Project
Rename your folder from
my_new_projectto a name of your choice. Adhere to Python conventions by keeping your project name all lowercase and connected with underscores. For instance,
scotts_projectare suitable project names.
Open the file
new_project_project/pyproject.tomland update the name here as well. For example:
[project] name = "scotts_project" # <--- updated with your new name
Naming the App
Determine how your code should be imported. For instance, you may want your workflows to be loaded like so:
from example_app.workflows import Example__Workflow__Settings
Use the first part of this (
example_app) to rename the
example_appfolder. The Python conventions (described above) also apply here. For instance,
simmate_cleaseare informative and memorable project names. Here's how they would work:
from simmate_clease.workflows import ClusterExpansion__Clease__BasicSettings
Open the file
example_app/apps.pyand rename the class AND name property to match your app name. For example:
from django.apps import AppConfig class SimmateCleaseConfig(AppConfig): # don't forget the class name name = "simmate_clease"
While this file may seem trivial, it enables users to build complex apps that include many other apps / subapps. Beginners will likely never revisit this file.
Installing Your App¶
pyproject.tomlfile. This file instructs Python on how to install your code (and it doesn't require much to install a package ). As your project expands and requires other programs to be installed, you'll track them here. For now, no changes are needed.
While inside your new project folder, "install" the project to your conda environment in "--editable" (-e) mode. This allows you to make changes to your code, and Python will automatically incorporate your changes.
# replace "my_new_project" with the name of your project cd my_new_project pip install -e .
Verify the installation by running these lines in Python. You may need to restart your terminal/Spyder for this to work.
# Update code to use your new names import example_app from example_app.apps import ExampleAppConfig
You now have an installed app! However, Simmate is still unaware of its existence. We need to inform Simmate to load it.
Registering Your App¶
If you have explored the
Appssection of our documentaion, you will see that many apps are registerd using the
simmate config addcommand. We can use this command to register our app. Simply write out the python path to our
simmate config add 'example_app.apps.ExampleAppConfig'
ExampleAppConfigis the python class that we defined in the
Ensure the new configuration includes your new app:
simmate config show --user-only
Ensure Simmate can locate and load your app in Python:
from simmate.configuration import settings print(settings.apps) # you should see your new app!
Ensure Simmate can configure your new app and its tables properly:
from simmate.database import connect
You now have registerd your app with Simmate and confirmed everything is working
Sharing your app w. others¶
If you are an experienced python programmer, you probably noticed this already... But Simmate Apps are essentially the creation of a new Python package. In fact, our
start-project command functions like a "cookie-cutter" template.
This has significant implications for code and research sharing. With a fully-functional and published Simmate project, you can share your code with other labs via Github and PyPi. This allows the entire Simmate community to install and use your custom workflows with Simmate. For them, the process is as simple as:
pip install my_new_project
We won't cover publishing packages in our guides (because it's an advanced topic), but feel free to reach our to our team if you need help
Alternatively, you can request to merge your app into our Simmate repository, making it a default installation for all users. Whichever path you choose, your hard work will be more accessible to the community and new users!