Skip to content

Updates

Check your installed version

When importing simmate and establishing a connection to the database, a warning message will be displayed if your version is not the most recent one. You can also verify this via the command-line:

simmate version

Upgrading to the Latest Version

We strongly advise installing simmate in a fresh conda environment instead of updating it within your current environment: 

conda create -n my_env -c conda-forge python=3.11 simmate

Ensure that the expected version is installed: 

simmate version

Update your database to be compatible with the new installation: 

simmate database update

Warning

The command simmate database update is only effective from v0.15.0 onwards. Earlier versions of simmate necessitate a complete database reset when updating versions. So, if your original database version is v0.14.0 or earlier, you must run simmate database reset.

Understanding Version Numbers

Our releases follow semantic versioning. This implies that versions (e.g., v1.2.3) correspond to MAJOR.MINOR.PATCH. Each version number increases following these changes:

  • MAJOR = incompatible API changes
  • MINOR = addition of new functionality (without API changes)
  • PATCH = bug fixes and documentation updates (without API changes)

There is one significant exception to the above rules -- MAJOR=0 releases. Any v0.x.y release is considered developmental, where APIs are subject to change and are not deemed stable.

Upcoming Release

Tip

To view ongoing changes that haven't been finalized or merged yet, check our active pull-requests on GitHub

Enhancements

  • added frontend framework and docs, based off of a fork of django-unicorn
  • added custom API token generation and auth backend
  • added CSV download button on the Data web views
  • added api_view decorator for basic REST endpoints
  • added file_upload web component
  • added export of SDF metadata
  • added foriegn_key_link util
  • added tags support in dynamic components
  • added html table and entry context hooks
  • added loading_spinner tag for unicorn components
  • added plotly_figure filter tag for rendering plots
  • added report features to database tables and data_explorer views
  • added StatusTracking model to database.base_data_types
  • added is_dueterated methods to Molecule
  • added web scrape of news archive for apps.bcpc
  • added apps.ppdb
  • added dev apps chatbot and analysis_dashboard
  • added database.external_connectors utils
  • added proof of concept htmx app for frontend forms
  • added toolkit.datastores and toolkit.dataframes helper modules
  • added molecular and poc apps to the list of df
  • allow conditional postgres-rdkit extension with settings flag
  • added startup_method hook to simmate workers

Refactors

  • refactored website's workflow tab to use new API backend
  • removed django-contrib-comments, django-crispy-forms, dj-database-url, django-filter, and djangorestframework dependencies
  • update breadcrumbs tag to include deprec breadcrumb_active
  • workflows results in the web ui now exists within the Data tab. The workflow tab has been limited to submission, docs, and analytics
  • DynamicApiView was split up into separate views for easier debugging and future enhancements
  • website.engine apps and others are condensed into core_components, data_explorer, and workflows apps
  • refactored toolkit.featurizers module
  • moved all of simmate.engine module into simmate.workflows

Fixes

  • fix Data tab in website view failing to load due to molecule template
  • fix workflow names that have captial letters next to eachother (e.g, LogDWorkflow --> log-d-workflow)
  • fix parse_multiselect util when nested in a create_many form
  • fix unicorn.loading activity when Unicorn.call() js is called
  • fix to_sdf export

v0.18.0 (2025.04.20)

Enhancements

  • added a molecular toolkit, which is a wrapper around rdkit that cleans up the python api
  • updated Data web pages and UI to be more user friendly
  • added frontend framework for building dynamic web forms/pages
  • enabled data management from web ui -- allowing users to create and update a dataset from the ui
  • added chemdraw support and beta apps for molecular datasets (eMolecules, Enamine, Chemspace, etc)
  • added Quantum Espresso support
  • added rdkit-postgres cartridge support
  • large updates to the BadELF app to support materials with covalent and metallic character

Refactors

  • django_unicorn dependency was forked and refactored into a custom interal version
  • REST APIs for data views no longer use django_rest_framework
  • add the simmate.apps.dev module for early-stage, experimental apps
  • the database.third_parties module is now moved into individual apps: materials_project, jarvis, aflow, and oqmd

Fixes

  • many misc fixes to the website UI and settings config

v0.17.0 (2024.05.20)

Enhancements

  • add api authentication via tokens for private Simmate servers
  • add tips for docker installations & permissions
  • allow custom django apps to be added to INSTALLED_APPS via extra_django_apps
  • allow override of django settings via django_settings
  • add several web UI components (e.g. select2 elements for forms)
  • add "Table Info" page and utils for dynamically building database docs
  • badelf app was reworked and now uses pybader for its core engine

Refactors

  • update docs for creating new Simmate apps with URLs

Fixes

  • fix show_columns bug when there are relations to basic django models (like User)
  • catch incorrect use of simmate database reset when using the maintenance database
  • fix typo in setting email env vars

v0.16.0 (2024.01.27)

Enhancements

  • added dotdict utility for easy dot-access with nested dictionary objects
  • all settings can be added via environment variables for cloud-based deployments
  • add @workflow decorator for easily creating basic workflows
  • add _incar_updates to VaspWorkflows for cleaner inheritance & syntax
  • add Docker builds for Quantum Espresso to help new users
  • add Docker builds for Bader to help new users
  • add simmate config command to help inspect and update settings

Refactors

  • Fully reimplemented how all settings are loaded
  • Revised all documentation and tutorials

Fixes

  • fix bug where user-provided command parameter is not properly loaded

0.16.1 (2024.01.28)

  • fix bugs for Docker-QE runs
  • fix typos in Getting Started tutorials

v0.15.0 (2024.01.04)

Enhancements

  • Allow custom html templates and static files that override those shipped by default
  • add simmate engine commands like stats-detail and workitems that show details of workitems in the database
  • updated third-party archives (Materials Project, COD, JARVIS, OQMD)
  • eased database updates between simmate versions by using django migrations
  • added bypass_nones utility to help handle imperfect datasets where not all entries have a column
  • misc updates to the website interface, especially to the data explorer pages
  • add Microsoft allauth support to sign in use external account
  • allow "login required" access to server via evironment variables (disabled by default)
  • allow "internal only" access to server via evironment variables (disabled by default)
  • add django-simple-history support to track user changes on specific models
  • add @check_db_conn decorator to help with database connection closures/timeouts
  • add simmate engine start-schedules which let's you configure periodic tasks for individual apps (e.g. check a table for updates every 5 minutes). Includes error handling and email alerts. (Note: this a quick alternative to full Prefect system)
  • add warren_lab app with Warren Lab preferred VASP settings
  • add badelf app with class oriented tools for performing BadELF analyses
  • add basic quantum espresso support

Refactors

  • remove mamba support now that libmamba is default conda solver
  • switch CI from mamba back to conda

Fixes

  • fix bug where workers incorrectly grab substring tag matches (e.g. a worker submited with the tag ex would incorrectly grab jobs like ex-01 or ex-02)

0.15.1 (2024.01.11)

  • refactor & fix bugs for warren_lab and badelf apps

v0.14.0 (2023.07.06)

Enhancements

  • add django-unicorn to deps to enable dynamic fullstack web UIs
  • add ChemDoodle js/css to website headers for use elsewhere
  • add "Example Scripts" section to doc website with several new scripts
  • many updates to the web UI to accomodate molecular datasets and workflows
  • add simmate engine commands to help with tags and different queues
  • add docs to help with simmate workers, clusters, and tagging
  • add simmate-vasp command for common VASP utilities like testing config, plotting, and prepping inputs
  • add utilities to chunk larger than memory datafiles (csv, sdf, cifs, etc.)

Refactors

  • VASP potcar references to "element mappings" is now standarized to "potcar mappings"
  • refactor docs with new "Apps" section
  • full refactor of simmate engine commands. many have been shortened/renamed
  • restrategized workflows that use output files from others. The copy_previous_directory input parameter has been removed and replaced with workflow attributes like use_previous_directory and has_prerequisite, combined with an optional previous_directory parameter.

Fixes

  • fix bug where hyphens aren't allowed in the database name
  • fix guide for DO database setup
  • fix incorrect evolutionary search imports
  • hide pymatgen POTCAR warnings
  • fix github CI bug for MacOS being unstable
  • fix bug for zombie jobs causing evolutionary search to hang
  • fix premature triggering of frozen error

v0.13.0 (2023.03.06)

Enhancements

  • add relax_bulk and relax_endpoints parameters to optionally turn off pre-relaxations in NEB
  • add CLEASE app for cluster expanison calculations (these workflows are highly experimental at the moment - so use with caution)
  • update "bad-elf" workflow to accept an empty-atom template structure or a list of empty sites
  • add python 3.11 support
  • simmate database reset now supports Postgres (requires admin user)
  • docker images are now published to DockerHub and Github packages

Refactors

  • calculators module is now the apps module and terminology is changed throughout the repo
  • many dependencies are reworked to optional dependencies as all apps are now optional
  • workflow_engine module has been renamed to engine to help shorten commands and import lines
  • rework CI to use mamba instead of conda
  • pull out dependencies for some apps that are now optional
  • reorganize Incar class and move some functionality to general utilities
  • NEB module is reorganized to help with building custom sets

Fixes

  • fix site ordering in NEB supercell structures
  • improve installation speed and guide users to conda alternatives like mamba
  • clean up docs and fix several links
  • apps are now registered to the web UI

Warning

The refactoring of simmate "apps" led to many breaking changes in the python API. We strongly recommend clearing your ~/simmate/ directory, especially the my_env-apps.yaml file because app names have changed.

0.13.1 (2023.03.11)

  • recover from connection already closed errors after long workflow runs
  • fix bug where simmate database reset fails when there is no database postgres available
  • update django regression of django.db.backends.postgresql_psycopg2 to django.db.backends.postgresql
  • fix bug where simmate cannot read vasp results due atypical number (e.g. -0.33328-312)
  • fix bug where postgres cannot json serialize bs or dos results (int64 numbers)
  • fix incorrect pointing of VASP potcars in matproj presets
  • from from_directory method of the Relaxation database class
  • fix HSE bandstructure and DOS kpoint file writing

0.13.2 (2023.03.20)

  • fix pickling error for workflow.run_cloud command
  • simmate.website.third_parties module is now the data_explorer module. With this, you can now specify custom database tables to appear in the "Data" section for the web UI

v0.12.0 (2022.10.23)

Enhancements

  • add structure creators for ASE, GASP, PyXtal, AIRSS, CALYPSO, USPEX, and XtalOpt as well as documentation for creators.
  • add simmate version command
  • changelog and update guide added to documentation website
  • add show-stats, delete-finished, and delete-all commands to workflow-engine
  • add Cluster base class + commands that allow submitting a steady-state cluster via subprocesses or slurm
  • add started_at, created_at, total_time, and queue_time columns to Calculation tables
  • add exlcude_from_archives field to workflows to optionally delete files when compressing outputs to zip archives
  • various improvements added for evolutionary search workflows, such as parameter optimization, new output files, and website views
  • add Fingerprint database table and integrate it with Fingerprint validator
  • support >2 element hull diargrams and complex chemical systems

Refactors

  • optimize get_series method of relaxation.vasp.staged
  • reorganize selectors module for evolutionary structure prediction

Fixes

  • fix dynamic loading of toolkit structures from third-party databases
  • fix race condition with workers and empty queues
  • increases default query rate for state.result() to lessen database load

v0.11.0 (2022.09.10)

Enhancements

  • REST API fields can now be specified directly with the api_filters attribute of any DatabaseTable class & fields from mix-ins are automatically added
  • add archive_fields attribute that sets the "raw data" for the database table & fields from mix-ins are automatically added
  • accept TOML input files in addition to YAML
  • convergence plots and extras are now written for many workflow types (such as relaxations)
  • when use_database=True, output files are automatically written and the workup method is directly paired with the database table.
  • NEB workflow now accepts parameters to tune how distinct pathways are determined, including the max pathway length and cutoffs at 1D percolation.
  • add MatplotlibFigure and PlotlyFigure classes to help with writing output files and also implementing these figures in the website UI
  • update website to include workflow calculator types and add API links
  • custom projects and database tables are now registered with Simmate and a intro guide has been added
  • continued updates for structure-prediction workflows
  • add inspection of methods for default input values and display them in metadata

Refactors

  • the website.core_components.filters module has been absorbed into the DatabaseTable class/module
  • yaml input for custom workflows now matches the python input format
  • workup methods are largely depreciated and now database entries are returned when a workflow has use_database=True
  • several NEB input parameters have been renamed to accurate depict their meaning.
  • customized workflow runs now save in the original database table under the "-custom" workflow name
  • structure_string column renamed to structure to simplify api logic
  • clean up toolkit.validators module and establish fingerprint base class
  • calculators and workflows modules are now based on simmate apps

Fixes

  • fix bug in windows dev env where simmate run-server fails to find python path
  • fix bug in workflows explore command where 'vasp' is the assumed calculator name
  • fix broken example code in custom workflow docs
  • fix broken website links and workflow views

0.11.1 (2022.09.12)

  • fix transaction error with workers on a PostGres backend

v0.10.0 (2022.08.29)

Enhancements

  • add NEB base classes to inherit from for making new subflows
  • improve formatting of logging and cli using typer and rich
  • cli now supports auto-completion to help with long commands
  • add convergence_limit parameter to evolutionary search that works alongside limit_best_survival. This will absorb minor changes in energy with equivalent structures from prolonging the search.
  • add ExtremeSymmetry transformation to attempt symmetry reduction on disordered structure
  • account for structures in fixed-composition having fewer nsites than input becuase of symmetry reduction during relaxation. Also, add min_structures_exact parameter to ensure we have at least N structures with the expected number of sites
  • add experimental variable-composition (variable refers to nsites, not stoichiometry) and binary-composition evolutionary searches
  • allow custom workflows to run from yaml
  • update MatProj data to new api, and add severl new columns for data (e.g. mag + band gap)

Refactors

  • isolate optional dependencies so that our install is smaller
  • remove click in favor of higher-level package (typer)
  • pre_standardize_structure and pre_sanitize_structure functionality is now merged in to a standardize_structure parameter that accepts different mode. symmetry_tolerance and angle_tolerance parameters can also modify the symmetry analysis done.
  • metadata files are now numbered to allow multiple metadata files in the same directory
  • refactor & clean up transformation module for readability
  • remove SimmateFuture class and merge functionality into WorkItem
  • switch from pdoc to mkdocs for documentation and remove get_doc_from_readme. Code and doc organization are now decoupled.
  • rename run commands based on user preference. the run is now run-quick. run-yaml is now run. run-cloud now assumes a yaml input.
  • remove tqdm dependency in favor of rich.progress
  • refactor transformations to static methods

Fixes

  • fix module not found error by adding ASE to dependencies
  • fix bug with postgres database trying to delete sqlite locally
  • fix dask throwing errors with logging
  • fix bug where fixed-composition searches fail to detect individuals that have been symmetrically reduced (and therefore have fewer nsites than expected)
  • fix evolutionary search failures when writing output files while files are opened/locked
  • fix NEB workflows failing due to Walltime handler
  • fix NEB workflows hints for workup failure due to missing start/end image folders

v0.9.0 (2022.08.17)

Enhancements

  • improve the warning associated with workflow failure because of "command not found" issues
  • workers now ignore and reset tasks that fail with "command not found". 2 workers failing with this error will result in the WorkItem being canceled
  • RandomWySites can now generate wyckoff combinations lazily (or up front) depending on use case
  • add simmate utilities command group with archive-old-runs
  • add start-cluster command for starting many local workers
  • add structure-prediction workflows
  • add plotting/output utilities to EvolutionarySearch and relaxation.vasp.staged

Refactors

  • evolutionary search now delay creations, transformations, and validation until runtime (used to be at time of structure submission)
  • directory, compress_ouput, and run_id are now default input parameters for subclasses of Workflow. If these are unused, the run_config must include **kwargs
  • add isort for organizing module imports throughout package

Fixes

  • fixed when source is not being registered by several workflows
  • fix docker image for installing anaconda, blender, and simmate on ubuntu

v0.8.0 (2022.08.11)

Enhancements

  • NEB workflows now accept parameters for changing supercell size and number of images used
  • add HSE workflows for static energy, relaxation, and DOS/BS electronic states
  • add NPT and MatProj molecular dynamics workflows
  • add SCAN workflows for static energy and relaxation
  • test files can be provided within zip files, fixing excessive line counts on git commits
  • add simmate worker that can run "out-of-box" and requires no set up
  • add logging for useful debugging and monitoring of workflows
  • pinned dependencies to maximum versions and manage with dependabot

Refactors

  • to simplify the creation of new workflows, S3Task is now S3Workflow and database tables are dynamically determined using the workflow name
  • workflows of a given type (e.g. relaxation or static-energy) now share database tables in order to simplify overall database architecture
  • migrate from os.path to pathlib.Path throughout package
  • isolate prefect use to separate executors
  • updated tutorials for new workflow engine and workers
  • remove use of setup.py in favor of pyproject.toml

v0.7.0 (2022.07.19)

Enhancements

  • add guide for installing VASP v5 to Ubuntu v22.04 (@scott-materials, #183)
  • add simmate database load-remote-archives command and load_remote_archives utility that populates all tables from database.third_parties
  • add load_default_sqlite3_build utility that downloads a pre-built database with all third-party data present. This is an alternative to calling load_all_remote_archives if you are using sqlite3 and saves a significant amount of time for users.
  • standardize workflow naming. Note this breaks from python naming conventions for classes (#150)
  • dynamically determine register_kwargs and rename property to parameters_to_register
  • add full-run unittests that call workflows and vasp (without emulation)
  • add walltime error handler that properly shuts down calculations when a SLURM job is about to expire
  • add option to restart workflows from a checkpoint
  • automatically build api documentation using github actions

Refactors

  • refactor start-worker command to use prefect instead of the experimental django executor
  • remove experimental workflow_engine.executor
  • move contents of configuration.django.database to database.utilities
  • upgraded to Prefect v2 ("Orion"). This involved the refactoring the entire workflow_engine module, and therefore the entire workflow library. (#185).

0.7.1 (2022.07.19)

  • fix incorrect handling of prefect v2 futures by workflows

0.7.2 (2022.08.03)

  • fix missing SVG files for web UI (#196).

0.7.3 (2022.08.04)

  • fix incorrect passing of source in NEB all-paths workflow causing it to fail

v0.6.0 (2022.06.25)

Enhancements

  • add AflowPrototypes to the database.third_parties module (only includes data distributed through pymatgen)
  • add new modules to toolkit.structure_prediction and toolkit.creation, including ones to provide known, substitution, and prototype based structures.
  • add created_at and updated_at columns to all database tables
  • check if there is a newer version of Simmate available and let the user know about the update
  • add experimental badelf workflow for determining electride character
  • add electronic-structure workflow which carries out both DOS and BS calculations
  • add database_obj attribute to the toolkit.Structure base class that is dynamically set

Refactors

  • standardize database_table attribute for workflows by merging calculation_table and result_table attributes (#102)
  • removed use of -s, -c, and -d shortcuts from the workflows commands
  • refactor relaxation/staged workflow to run in single parent directory
  • refactor evolutionary search algorithm (alpha feature)
  • condense where parsing/deserialization of workflow parameters occurs to the refactored the load_input_and_register task. Originally, this would occur in multiple places (e.g. in the CLI module before submission, in the workflow run_cloud method, in the LoadInputAndRegister task, etc.) and involved boilerplate code. (#173)
  • refactor experimental features register_kwargs and customized workflows
  • refactor LoadInputAndRegister and SaveOutputTask to load_input_and_register and save_result

Fixes

  • fix import for visualization.structure.blender module (@bocklund, #180)
  • fix bug where command or directory improperly passes None when they are not set in the simmate workflows run command
  • fix bug where update_all_stabilities grabs incomplete calculations (#177)
  • fix bug where SCF calculation is not completed before the non-SCF DOS or BS calculation and causes the workflows to fail (#171)
  • fix bug for Bader workflow by registering the prebader workflow (#174)
  • fix bug where source is not determined with yaml-file submissions (#172)

v0.5.0 (2022.05.30)

  • update CI to test all OSs and pin pytest<7.1 as temporary fix for #162
  • fix spelling typos in keyword_modifiers (@laurenmm, #165)
  • users can now apply their own unique keyword modifiers to Incars -- such as how we allow "__per_atom" or "__smart_ismear" tags on Incar settings. This change involved refactoring how keyword_modifiers are implemented for the vasp.inputs.Incar class. Rather than static methods attached to the base class, modifiers are now dynamically applied using the add_keyword_modifier classmethod.
  • large update of calculators.vasp.tasks module where many new presets are reimplemented from pymatgen.io.vasp.sets. This includes robust unit testing to confirm that generated inputs match between simmate and pymatgen (see #157 for a list of presets)
  • catch error with vasp freezing when Brmix handler switches to kerker mixing (@becca9835, #159)

v0.4.0 (2022.04.24)

  • add description_doc_short + show_parameters to workflows and use these to update the UI
  • add django-allauth dependency for account management and google/github sign-ins
  • archive directory as simmate_attempt_01.zip whenever an error handler is triggered
  • depreciate the workflow parameter use_prev_directory in favor of copy_previous_directory

v0.3.0 (2022.04.19)

  • add highly customizable VASP workflow
  • add Bader analysis and ELF workflows
  • update module readmes to warn of experimental features
  • reorganize toolkit module

v0.2.0 (2022.04.15)

  • start the CHANGELOG!
  • refactor API views and add SimmateAPIViewSet class
  • refactor simmate start-project command and underlying methods
  • refactor simmate workflow-engine run-cluster command and underlying methods
  • continue outlining file_converters module

v0.1.4 (2022.04.12)

  • web interface styling
  • minor bug fixes

v0.0.0 (2022.03.28)

  • initial release
  • adding tests and docs