Creating new project files¶
-
To create a new project, navigate to a folder where you'd like to store your code and run...
simmate start-project
-
Doublecheck that you see a new folder named
my_new_project
. Open it up and you should see 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
-
Make note that we have a folder named
example_app
. This is where our code will go. You can have as many app folders as you'd like (and in extreme scenarios even have apps within other apps).
Name our project and app¶
Danger
Once you choose a name, stick with it. Changing your project name or app name after it has
been installed can lead your code failing with ModuleNotFound
errors.
** Name the project **
-
Rename your folder from "my_new_project" to a name of your choosing. Try to follow python conventions and keep your project name all lowercase and connected with underscores. For example,
warren_lab
orscotts_project
are good project names. -
Open the file
new_project_project/pyproject.toml
and change the name here as well.[project] name = "my_simmate_project" # <--- update with your new name
** Name the app **
-
Decide on how your code should be imported. For example, you may want your workflows to be loaded like so:
from example_app.workflows import Example__Workflow__Settings
-
Take the first part of this (
example_app
) and rename theexample_app
folder to match this. The python conventions (described above) also apply here. For example,simmate_abinit
orsimmate_clease
are informative and good project names. These let the user know what's in your app and they're easy to remember. 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.from django.apps import AppConfig class SimmateCleaseConfig(AppConfig): # don't forget the class name name = "simmate_clease"
Note
This file might seem silly, but it allows users to build complex apps that include many other apps / subapps. Beginners will likely never look at this file again.
Install our app¶
-
Open the
pyproject.toml
file. This file is what tells Python how to install your code. It doesn't take much to install a package. As you project gets larger and needs other programs installed, you'll make note of them here. For now, nothing needs to be changed.
-
While inside your new project folder, we want to "install" the project to your conda envirnment in "--editable" (-e) mode. This means you'll be make changes to your code and Python should automatically use your changes.
# replace "my_new_project" with the name of your project cd my_new_project pip install -e .
-
Make sure this install worked by running these lines in python. You may need to restart your terminal/Spyder for this to work.
import example_app
from example_app.apps import ExampleAppConfig
import simmate_clease
from simmate_clease.apps import SimmateCleaseConfig
You now have an installed app! But one issue remains: Simmate still doesn't know it exists yet. We need to tell Simmate to load it.
Register your app with Simmate¶
-
Go to your simmate configuration folder. Recall from earlier tutorials that this where your database is stored, and it is located at...
# in your home directory cd ~/simmate/
-
Look for the file
~/simmate/my_env-apps.yaml
, which is named after your conda environment. Open it up and you'll see we have apps already installed with Simmate:- simmate.workflows.configs.BaseWorkflowsConfig - simmate.apps.VaspConfig - simmate.apps.BaderConfig - simmate.apps.EvoSearchConfig
-
In this file, add the following line at the bottom
- example_app.apps.ExampleAppConfig
-
Make sure Simmate can find and load your app in python
from simmate.configuration.django.settings import SIMMATE_APPS print(SIMMATE_APPS) # you should see your new app!
-
Make sure Simmate can configure your new app and it's tables properly
from simmate.database import connect
Tip
If you ever want to stop using this app, you can delete it from your ~/simmate/my_env-apps.yaml
file.