Creating Simmate Apps¶

Tip

If you prefer learning from full examples, you can explore other apps built with Simmate at src/simmate/apps

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 get_workflow function)
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:
```
simmate create-app
```

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¶

Danger

Once you've chosen a name, stick with it. Altering your project or app name post-installation can result in ModuleNotFound errors.

Naming the Project

Rename your folder from my_new_project to a name of your choice. Adhere to Python conventions by keeping your project name all lowercase and connected with underscores. For instance, warren_lab or scotts_project are suitable project names.
Open the file new_project_project/pyproject.toml and 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_app folder. The Python conventions (described above) also apply here. For instance, simmate_abinit or simmate_clease are 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.py and rename the class AND name property to match your app name. We also add labels for the web ui to use. For example:

from django.apps import AppConfig

class SimmateCleaseConfig(AppConfig):
    name = "simmate_clease"

    # These settings determine in the web ui (if you add a urls.py to your app)
    verbose_name = "CLEASE"  
    description_short = "utilities for running cluster-expanison calcs using CLEASE"

Note

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¶

Open the pyproject.toml file. 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 .   # <-- don't forget the period!
```
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 Apps section of our documentaion, you will see that many apps are registerd using the simmate config add command. We can use this command to register our app. Simply write out the python path to our Config:
```
simmate config add 'example_app.apps.ExampleAppConfig'
```
Note

ExampleAppConfig is the python class that we defined in the apps.py file
Tip

If your app has another third-party Django dependency, you must register that as well. To do this, use the extra_django_apps setting. All apps in this setting will be added to Django's INSTALLED_APPS setting. For example:
```
apps:
    - example_app.apps.ExampleAppConfig

extra_django_apps:
  - django_tables2
  - django_celery_results
```
extra_django_apps will be added to INSTALLED_APPS added ahead of any Simmate apps. If this does not work for your desired dependency, please contact our team for support.
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

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
Adding example_app.apps.ExampleAppConfig to their ~/simmate/my_env-settings.yaml

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

Note

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!

Custom Django settings¶

Danger

This section is only for experts. Try to avoid updating Django settings because you could unintentially break some Simmate apps/features.

Advanced users may want to have full control over django settings. Before you mess with Simmate's default settings for Django, we highly recommend reading through our settings.py file located here:

https://github.com/jacksund/simmate/blob/main/src/simmate/configuration/django/settings.py

You can update hard-coded django settings using the simmate setting file (~/simmate/settings.yaml) like so:

django_settings:
    CRISPY_TEMPLATE_PACK: bootstrap4

If you need even more control (such as providing a custom settings.py entirely), please reach out to our team so that we can add support for your needs.