Overview

lcopt - An interactive tool for creating fully parameterised Life Cycle Assessment (LCA) foreground models

Lcopt is a python module for creating fully parameterised LCA foreground models using a Flask based interactive GUI developed by James Joyce.

Features

• Intuitive GUI based on drawing of flow sheets
• Flexible model setup
• Integration with SimaPro and Brightway2
• Run LCA analyses and explore the results from inside the GUI
• Export and share your results using lcoptview

Introduction

What does it do?

LCOPT is designed to provide a simple and intuitive way to create ‘fully parameterised’ Life Cycle Inventory foreground models.

What’s a Life Cycle Inventory foreground model?

To conduct a Life Cycle Assessment (LCA) we need to create a model of the life cycle of a given product or process which we can then use to estimate the potential environmental impact which results. This includes extraction of raw materials, processing, transport, use, disposal etc. etc.

Because each item used in a life cycle has it’s own set upstream processes the LCA model tends to be split into the foreground system - the processes under the control of the person doing the LCA - and the background system - the rest of the industrial economy which provides the materials and services required by the foreground system.

Background system models are either determined by data providers (e.g. ecoinvent) or can be customised using Ocelot.

The foreground model is a set of linked unit processes. A unit process describes a stage in the life cycle. It is basically a list of the exchanges required to produce one unit of an intermediate (or final) product. These exchanges can either be inputs from the technosphere - the human constructed industrial economy - or resources from or emissions to the biosphere. Technosphere exchanges can either come from the background system or other processes in the foreground system.

For example, when you make a cup of tea you make some boiling water, add this to some tea leaves, add some milk, then use/drink it.

Flow chart

The boiling water is created in the unit process kettle which takes inputs from the background system of water and electricity and emits a small amount of water vapour to the biosphere.

The next unit process is teapot. This takes an input of boiling water from our first process, and tea leaves from the background system to produce black tea.

Finally, teacup takes an input of black tea from the teapot process and milk from the background system Note : we’re making a proper British cup of tea!

We now have a foreground model for our cup of tea LCA.

Why use LCOPT for creating foreground models?

How you create your foreground model is up to you.

Simple models can be constructed in Excel. More complex models can be created in commercially available softwares such as SimaPro or GaBi, or freeware such as OpenLCA.

These fully featured software packages have a steep learning curve, can cost a lot of money, or require administrator rights to run (which can be an issue with university or company owned computers).

Lcopt is free, open source and written in Python. You can install it without admin rights and it runs in a normal web browser. It’s designed to be simple and intuitive, but powerful enough to conduct proper LCAs.

How do you create foreground models in LCOPT?

When you start an LCA, its usually a good idea to draw out a flow diagram of the system you’re modelling on a piece of paper. This helps you identify the unit processes involved, the inputs they use and the extent of the foreground system you might be able to get primary data for.

Creating foreground models in Lcopt is as simple as drawing out your flow chart.

Instead of having to write out lists of exchanges to describe each unit process, you simply draw out a flow sheet of your process. You can add processes, link them together and add inputs and outputs. In the background Lcopt compiles these exchange lists, and gives each link a parameter. When you’ve finished your drawing you have a fully parameterised foreground model.

What does fully parameterised mean?

In order to analyse your LCA model, you need to know how much of each exchange is required by each unit process. In most softwares the default is to hard code these values in the unit process itself. This is great for a one-off model, but can be a real hassle if there are multiple variants of your system which you want to assess and compare.

Taking the example from above, some people like their tea with milk, some like it black. Some people like strong tea (with more tea leaves) others like it weaker. If you want to compare weak milky tea with strong black tea you’d need to create two different teapot processes (one for weak, one for strong) and two different teacup processes (one for milky, one for black), with the correct exchange amounts, and links to the version of teapot with the correct output.

If you then decide you want to model strong milky tea or weak black tea you need to create more unit processes…

Most LCA softwares allow you to replace the values in the unit processes with parameters, which you can then vary externally to create scenarios. Choosing, typing out and remembering parameters can be a boring and time consuming task though. With Lcopt it’s all done automatically in the background. Every link in the model is given a parameter instead of a value. By default, the model is ‘fully parameterised’.

This makes creating the model a lot quicker and the modelling and analysis a lot more flexible.

How do you go from a flow sheet to a model?

To go from an unquantified flow sheet to a meaningful LCA model, the first thing you need to do is create a parameter set. This provides a value for each link in a given scenario.

You can either enter an explicit value, or you can tell the model to generate its own value based on a function/formula. To help this you can also create global parameters to use in these functions.

For example, the amount of electrity (kWh) a kettle uses to boil a litre of water can be determined by it’s power rating (kW) and the amount of time it takes to boil (minutes).

You can create a global parameter for power rating and another one for boil minutes. You can then tell the model to generate a value for the input of electricity to kettle using the function power_rating * boil_mins / 60.

Now you can easily compare different kettles in your cup of tea LCA.

You can use any parameter in a function, including inputs to any process. For example, if you want to add transport of an input (in units of kg.km) you could create a ‘transport distance’ parameter, and tell Lcopt to work out the amount of ‘transport’ required by multiplying the amount of your input (kg) by the distance (km). Now whenever you change the amount of your input, the transport of that input automatically changes too.

Once you have a ‘default’ parameter set you can duplicate it and edit whichever parameters you need to describe a new scenario.

For example you can change the parameter for the input of milk to teacup to zero to model a black tea scenario, or increase the input of tea leaves to teapot to model a strong tea scenario.

How do you analyse a model?

Hotspot chart

To analyse the model you have two options.

If you have a copy of SimaPro and are using lcopt as an easy way to generate a fully parameterised foreground model, you can export the model as a SimaPro .csv file and the parameter sets as an .xlsx file.

The second option is to run the analysis directly from Lcopt. This uses Brightway to do the calcuations. Brightway is an open source LCA software also written in Python.

When you analyse a model from within Lcopt for the first time it creates a Brightway project. The foreground model is stored as it’s own separate database within the project, with links to the biosphere and technosphere databases.

Lcopt calculates all of the parameters for each parameter set and then modifies the exchanges in the Brightway database before running the LCA calculations for that scenario.

Tree diagram

You can choose from over 700 different impact assessment methods (don’t worry, there is a search function), and use as many as you like in one go. The default set is climate change (IPCC 2013 100a) and human toxicity (USEtox).

Lcopt’s results screens contain bar charts, pie charts, tree diagrams, hotspot charts and tables. Charts can be exported to image files (300 dpi .png with transparent backgrounds) and the tables exported as Excel files.

Once the analysis has been run you can open the model in Brightway as you would any other project if you need to conduct a more detailed analysis. Note however that Brightway will only ‘remember’ the last scenario you ran so to do this it might be best to create your model with only one parameter set.

How do I get started?

To get started, follow the installation instructions on the next page, learn how to launch lcopt in your browser in the usage instructions then check out the video runthrough to see how to make the cup of tea model using Lcopt.

Installation

Basic Installation

Recommended Installation

The easiest way to install lcopt is via conda. This ensures the version of Python (3.6) is correct, all of the dependencies are correct and there are no conflicts. You can also do it in only 3 commands.

If you don’t have conda installed yet, first install Miniconda (available here)

1. On the command line/console, create a new environment called lcopt:

   conda create -n lcopt python=3.6
   

2. Activate the lcopt environment using one of these:

   # Mac/Linux
   source activate lcopt
   # Windows
   activate lcopt
   

3. Install lcopt:

   conda install -y -q -c conda-forge -c cmutel -c haasad -c pjamesjoyce lcopt
   

Setting up brightway2 for lcopt

To use the interactive analysis feature, you need to set up brightway2 to play nicely with lcopt.

Lcopt needs to set up its own brightway project template so that it can create a new brightway project for each of your models using this template.

Step 1. Download the Ecoinvent 3.3 cutoff database (Ecoinvent license required)

Note

Note - if you don’t have an ecoinvent license but want to try out lcopt, it can also be used with the freely available FORWAST database Alternative setup - FORWAST.

Log into ecoinvent.org and go to the Files tab

Download the file called ecoinvent 3.3_cutoff_ecoSpold02.7z

Extract the file somewhere sensible on your machine, you might need to download 7-zip to extract the files.

Make a note of the path of the folder that contains the .ecospold files, its probably <path/extracted/to>/datasets/

Step 2a. lcopt-bw2-setup at the command line

At the command line type:

lcopt-bw2-setup path/to/ecospold/files # use "" if there are spaces in your path

Step 2b. Or run the setup utility in a jupyter notebook/python shell

Fire up your chosen python shell, then use:

from lcopt.utils import lcopt_bw2_setup
ecospold_path = r'path/to/ecospold/files' # put your own path in here
lcopt_bw2_setup(ecospold_path)

It’ll take a while, but once its done it’ll return True if it worked properly.

Running the setup utility in a python shell also allows you to overwrite your existing configuration if something has gone wrong by using lcopt_bw2_setup(ecospold_path, overwrite=True)

Alternative setup - FORWAST

Lcopt can be used without an ecoinvent license by using the FORWAST database instead.

Option 1. Download lcopt_bw2_setup.py and use that instead

At the command line type:

lcopt-bw2-setup-forwast

Option 2. Run the setup utility in a jupyter notebook/python shell

Fire up your chosen python shell, then use:

from lcopt.utils import lcopt_bw2_forwast_setup
lcopt_bw2_forwast_setup()

It’ll take a while, but once its done it’ll return True if it worked properly.

As above, you can overwrite an existing configuration using overwrite=True

Getting Started

Set up the background databases

Set up with ecoinvent

Set up with FORWAST

The best way to get started with Lcopt is to explore one of the example models.

First make sure you’ve set up either ecoinvent or FORWAST as a background database.

Then activate your lcopt environment, and use the command line command lcopt-launcher to launch Lcopt

activate lcopt
cd C:\Users\pjjoyce\Documents\01_Lcopt_models
lcopt-launcher

This dialog will appear:

Choose Open Example Model

The video below runs through the steps required to make the example model.

Video

Using Lcopt

Creating and loading your own models

There are 2 options for using lcopt’s GUI (LCOPT INTERACT) to create and view your own models

Option 1. lcopt-launcher command line entry point (Simpler, only access to GUI)

Using this option, you can launch lcopt from the command line/console and use the GUI from then on.

Open the console/command line.

Activate your lcopt environment, cd into the folder you want to store your model in then simply use lcopt-launcher

activate lcopt
cd C:\Users\pjjoyce\Documents\01_Lcopt_models
lcopt-launcher

You’ll get an option to either create a new model or load an existing one (or to view the example model).

If you choose to create a model you will be prompted for a name - this will be the model’s name and the default filename.

If you choose to load a model a file dialog will open and allow you to choose an existing .lcopt file.

Once you’ve made your choice, the GUI will open in your default browser.

Option 2. Jupyter notebooks (More complicated, more powerful)

Probably the best way to use lcopt is via a jupyter notebook. This gives you more access to the inner workings if you need to get at something you can’t see in the GUI.

cd into whatever folder you want your notebooks and lcopt models to be stored in, then start jupyter e.g.:

activate lcopt
cd C:\Users\pjjoyce\Documents\01_Lcopt_models
jupyter notebook

This will fire up the jupyter notebook server in your browser. Create a new notebook, give it a meaningful name.

Then in the first cell import lcopt:

from lcopt import *

Next create your LcoptModel:

model = LcoptModel('MyFirstModel')

or load an existing one:

model = LcoptModel(load = 'MyFirstModel')

Note

If you are using FORWAST instead of ecoinvent, you need to add the argument useForwast=True e.g. model = LcoptModel(load = ‘MyFirstModel’, useForwast=True)

Then launch the interactive model creator/analyser:

model.launch_interact()

LCOPT INTERACT - the GUI

Running the GUI via each of the options above launches a Flask server that gives you a nice UI to interact with the models. You can add processes, link them together, add biosphere and technosphere exchanges, and create parameter sets and functions using your parameters. It should be pretty intuitive, if you get stuck, try the ‘more info…’ buttons.

See the video in the Getting Started page for a runthrough of the functionality of the GUI.

When your model’s ready you can export it to SimaPro as a .csv file and the parameter sets you’ve created as an Excel file (Note: you need SimaPro developer to import the parameter sets from the Excel file).

To run the analyses interactively using brightway2, make sure you’ve completed the additional setup step (Setting up brightway2 for lcopt).

The ‘QUIT’ button in the top right hand corner will shut down the Flask server and tell you to close the window.

If you’re running from a jupyter notebook, this frees up the notebook again so you can run any commands you need to.

One useful command is model.save() which will save any unsaved changes (you can also save by clicking on the save button in LcoptInteract, but in case you forget you can use model.save())

The model is saved as a .lcopt file in your working directory (its really a .pickle file, but the .lcopt extension makes it easier to filter on in the lcopt_launcher file picker)

NOTE: The next time you run the GUI from a notebook you need to use:

model = LcoptModel(load = 'MyFirstModel')

If you don’t it’ll create a new blank model called ‘MyFirstModel’. If you do do this by accident fear not - it won’t overwrite your .lcopt file until you save it. Quit interact by hitting the QUIT button and go back and change your command (just don’t click the save button or run model.save() in the meantime)

Technical Documentation

lcopt.model

Module containing the LcoptModel class.

class lcopt.model.LcoptModel(name=[randomly_generated_string], load=False)

This is the base model class.

To create a new model, enter a name e.g. model = LcoptModel('My_Model')

To load an existing model use the load option e.g. model = LcoptModel(load = 'My_Model')

add_parameter(param_name, description=None, default=0, unit=None)

Add a global parameter to the database that can be accessed by functions

analyse(demand_item, demand_item_code)

Run the analyis of the model Doesn’t return anything, but creates a new item LcoptModel.result_set containing the results

create_process(name, exchanges, location='GLO', unit='kg')

Create a new process, including all new exchanges (in brightway2’s exchange format) in the model database.

Exchanges must have at least a name, type and unit field

create_product(name, location='GLO', unit='kg', **kwargs)

Create a new product in the model database

database_to_SimaPro_csv()

Export the lcopt model as a SimaPro csv file.

The file will be called “<ModelName>_database_export.csv”

export_to_bw2()

Export the lcopt model in the native brightway 2 format

returns name, database

to use it to export, then import to brightway:

name, db = model.export_to_bw2()
import brightway2 as bw
bw.projects.set_current('MyProject')
new_db = bw.Database(name)
new_db.write(db)
new_db.process()

generate_parameter_set_excel_file()

Generate an excel file containing the parameter sets in a format you can import into SimaPro Developer.

The file will be called “ParameterSet_<ModelName>_input_file.xlsx”

import_external_db(db_file, db_type=None)

Import an external database for use in lcopt

db_type must be one of technosphere or biosphere

The best way to ‘obtain’ an external database is to ‘export’ it from brightway as a pickle file

e.g.:

import brightway2 as bw
bw.projects.set_current('MyModel')
db = bw.Database('MyDatabase')
db_as_dict = db.load()
import pickle
with open('MyExport.pickle', 'wb') as f:
    pickle.dump(db_as_dict, f)

NOTE: The Ecoinvent cutoff 3.3 database and the full biosphere database are included in the lcopt model as standard - no need to import those

This can be useful if you have your own methods which require new biosphere flows that you want to analyse using lcopt

launch_interact()

This is probably the most important method in the model - you use it to launch the GUI

list_parameters_as_df()

Only really useful when running from a jupyter notebook.

Lists the parameters in the model in a pandas dataframe

Columns: id, matrix coordinates, description, function

load(filename)

load data from a saved .lcopt file

parameter_scan()

Scan the database of the model instance to generate and expose parameters.

This is called by other functions when items are added/removed from the model, but can be run by itself if you like

remove_input_link(process_code, input_code)

Remove an input (technosphere or biosphere exchange) from a process, resolving all parameter issues

rename(newname)

change the name of the model (i.e. what the .lcopt file will be saved as)

save()

save the instance as a .lcopt file

search_databases(search_term, location=None, markets_only=False, databases_to_search=None)

Search external databases linked to your lcopt model.

To restrict the search to particular databases (e.g. technosphere or biosphere only) use a list of database names in the database_to_search variable

unlink_intermediate(sourceId, targetId)

Remove a link between two processes

lcopt.utils

Module containing the utility function to set up brightway2 to work with lcopt

lcopt.utils.forwast_autodownload(FORWAST_URL)

Autodowloader for forwast database package for brightway. Used by lcopt_bw2_forwast_setup to get the database data. Not designed to be used on its own

lcopt.utils.lcopt_bw2_forwast_setup(use_autodownload=True, forwast_path=None, db_name='LCOPT_Setup_Forwast', overwrite=False)

Utility function to set up brightway2 to work correctly with lcopt using the FORWAST database instead of ecoinvent

By default it’ll try and download the forwast database as a .bw2package file from lca-net

If you’ve downloaded the forwast .bw2package file already you can set use_autodownload=False and forwast_path to point to the downloaded file

To overwrite an existing version, set overwrite=True

lcopt.utils.lcopt_bw2_setup(ecospold_path, overwrite=False, db_name='LCOPT_Setup')

Utility function to set up brightway2 to work correctly with lcopt.

It requires the path to the ecospold files containing the Ecoinvent 3.3 cutoff database.

If you don’t have these files, log into ecoinvent.org and go to the Files tab

Download the file called ecoinvent 3.3_cutoff_ecoSpold02.7z

Extract the file somewhere sensible on your machine, you might need to download 7-zip to extract the files.

Make a note of the path of the folder that contains the .ecospold files, its probably <path/extracted/to>/datasets/

Use this path (as a string) as the first parameter in this function

To overwrite an existing version, set overwrite=True

Contact

Get in touch

If you have any problems or questions, please raise an issue on the github page.

Contribute

If you want to contribute to Lcopt, please fork the github repository and open a pull request. Please accompany any new features with corresponding tests (written for py.test).

Citing Lcopt

Lcopt has been published in the Journal of Open Source Software.

You can download the citation in BibTeX for use in LaTeX or importing into Mendeley/other reference management software from here.

Or use the following citation:

Joyce, P.J., 2017. Lcopt - An interactive tool for creating fully parameterised Life Cycle Assessment (LCA) foreground models. Journal of Open Source Software, 2:16. doi:10.21105/joss.00339