Enhancing a Package: Adding Conda Environments
Follow these steps to integrate conda environments into your SyncroSim Package.
Using conda simplifies management of SyncroSim (or other) Packages and dependencies. We highly recommend using this feature when creating a SyncroSim Package using either R or Python. In this article, we will outline how to create Packages that take advantage of conda environments. We detail how to create conda environments and how to add conda support to your SyncroSim Packages.
Creating a Conda Environment
Step 1 - Creating your Conda Environment
From your Windows search bar, begin typing "miniconda". Open the "Anaconda Powershell Prompt (Miniconda3)" app that appears. Type in the following command to create a new environment and give it a name. In this example, the name will be "new_env".
conda create -n new_env
If you want to create an environment using a specific version of Python (e.g. Python 3.8), you would instead type the following command:
conda create -n new_env python=3.8
If your desired environment has been shared with you using a YAML file, you can create the environment with the command below. In this example, the name of the YAML file will be "helloworld.yml". Ensure the desired YAML file is located in your current working directory.
conda env create -f helloworld.yml
Note
Do not include any spaces in your environment’s name and follow any prompts to install necessary packages.
Activate your new conda environment with the following command:
conda activate new_env
Your new conda environment is now active.
Step 2 - Installing Packages
If you haven't already, you will need to configure the conda channel to install the necessary python or R packages. The python and R packages required for this tutorial are available from the conda-forge channel. Therefore, before installing, we must add the conda-forge channel to our conda configuration.
In the Anaconda Prompt (Miniconda3) terminal, enter the following command:
conda config -–add channels conda-forge
Next, we will install the required Packages.
Conda environments come with Python already installed, but not R. Therefore, the first package you need to install is base r.
conda install r-base
The R extension of SyncroSim is called rsyncrosim. To install it, use the following command.
conda install r-rsyncrosim
Note that you can install more than one Package at a time. For example, you can also install tidyverse and raster using the following command:
conda install r-base r-syncrosim r-tidyverse r-raster
When you are done modifying your environment, you can deactivate it.
conda deactivate
Step 3 - Exporting your Conda Environment
To add your conda environment to a custom SyncroSim Package, you must export it to a YAML file. First, using the command cd, navigate to the folder where you would like to save your YAML file. For the purpose of this tutorial, we will navigate to the helloworld folder.
cd C:\Documents\temp\helloworld
Give a new name to your environment when you export it. In this example, the new name will be "environment". If your environment is currently active, you can export your environment using the following command:
conda env export > helloworld.yml
If your environment is not currently active, you can use the following command:
conda env export new_env > helloworld.yml
Note
For more information on creating conda environments, visit the conda documentation.
Adding Conda Support
To add conda support to your SyncroSim Package, you must make a small change within the First and Second Model Transformer tags of your package.xml. There is a new attribute, called condaEnv, where you specify the conda environment to be used with your Package as a .yml file. As long as this attribute is present, SyncroSim will recognize that this Package uses conda environments. In the examples below, we use the example "helloworld.yml" file created in the section above.
<transformer
name="firstModel"
displayName="First Model"
isRunnable="True"
programName="Rscript"
programArguments="model.R"
configurationSheet="RunControl"
condaEnv="helloworld.yml">
<transformer
name="secondModel"
displayName="Second Model"
isRunnable="True"
programName="Rscript"
programArguments="model2.R"
configurationSheet="RunControl"
condaEnv="helloworld.yml">
To give users the ability to turn conda environments on/off, you will also need to add the following XML code to your layouts section:
<!--Library Datafeeds Layout-->
<layout name="coreforms_LibraryDatafeeds">
<group name="Options">
<item name="core_Rconfig"/>
<item name="core_Options" displayName="General"/>
</group>
</layout>
For more information on how to use SyncroSim Packages with conda in the SyncroSim user interface, visit the Conda Quickstart page.