Skip to content

Troubleshooting & FAQ

Common issues and frequently asked questions about the OptiScope Dash App.

Getting Started

Q: How do I start the Dash app?

Run the following command in your terminal:

python -m optiscope.dash_app.app

Then open http://127.0.0.1:8050 in your web browser.

Q: The app won't start. What should I check?

  1. Verify Installation: Ensure OptiScope is installed: pip show optiscope
  2. Check Dependencies: Install required packages: pip install optiscope[dash]
  3. Port Conflict: If port 8050 is in use, the app will try alternative ports
  4. Python Version: Ensure you're using Python 3.8 or higher

Q: Can I change the port the app runs on?

Yes, you can specify a custom port by modifying the app configuration or using environment variables (see the source code for details).

Data Loading

Q: What file formats are supported?

The Dash app supports: - CSV (.csv) - JSON (.json) - SQLite (.db, .sqlite) - DuckDB (.duckdb)

Q: My file upload fails. What could be wrong?

Common Issues: - File too large: Large files (>100MB) may timeout. Use database formats or connect directly. - Invalid format: Ensure your file matches one of the supported formats - Corrupted file: Verify the file can be opened with other tools - Missing columns: Ensure required columns (objectives, variables) are present

Q: How do I load very large datasets?

For large datasets: 1. Use database formats: SQLite or DuckDB are more efficient 2. Connect directly: Use "Connect to Database" instead of uploading 3. Pre-filter data: Load only relevant subsets 4. Use sets: Create sets to work with smaller subsets

Q: Can I load multiple optimization results?

Yes! The Data Manager supports multiple data sources. Each result is managed independently and can be selected in visualization pages.

Visualization Issues

Q: Plots are not showing or appear blank

Troubleshooting Steps: 1. Check data is loaded: Verify in Data Manager 2. Select a result: Ensure a result is selected in the dropdown 3. Select columns: Some pages require column selection 4. Refresh the page: Try reloading the browser 5. Check browser console: Look for JavaScript errors (F12)

Q: Plots are very slow or laggy

Performance Tips: 1. Reduce data size: Use sets to filter to fewer points 2. Limit columns: Select fewer variables/objectives 3. Use resampler: For time series, resampler activates automatically for >10k points 4. Close other tabs: Free up browser resources 5. Use modern browser: Chrome or Firefox recommended

Q: Colors don't match between plots

This is expected when different pages use different color schemes. To maintain consistency: - Use the same "Color By" selection across pages - Create and use sets for consistent grouping - Note that automatic color assignment may vary

Q: Can I export plots?

Yes! All Plotly-based plots have a camera icon in the toolbar for downloading as PNG. You can also use your browser's screenshot tools.

Sets and Filtering

Q: What are sets and why should I use them?

Sets are named collections of solution indices that allow you to: - Group related solutions - Filter visualizations - Track important solutions - Organize your analysis

Q: How do I create default sets?

  1. Go to Sets Manager
  2. Select your result
  3. Click Create Default Sets

This creates: feasible, non-feasible, pareto, optimal, and smart_pareto sets.

Q: My sets aren't showing in visualizations

Check: - Sets are created for the correct result - The result with sets is selected - The visualization page supports set filtering - Sets contain valid indices

Q: Can I edit set membership?

No, you cannot edit the indices of an existing set. To change membership: 1. Create a new set with the desired indices 2. Delete the old set if no longer needed

Data Management

Q: Where is my data stored?

Session Storage: - Data is stored in memory during your session - Uploaded files are temporarily stored - Data is lost when you close the app

Persistent Storage: - Use "Connect to Database" for persistent access - Export results to save them permanently - Database files remain on your filesystem

Q: Can I save my session?

Currently, sessions are not automatically saved. To preserve your work: 1. Export results: Use Data Manager export features 2. Save database: Connect to a database file instead of uploading 3. Document sets: Note set definitions for recreation

Q: How do I share my results with others?

Options: 1. Export to database: Create a SQLite/DuckDB file and share it 2. Share original files: Share the CSV/JSON files you uploaded 3. Screenshots: Export plots and share images 4. Documentation: Document your findings separately

Browser Compatibility

Q: Which browsers are supported?

Recommended: - Google Chrome (latest) - Mozilla Firefox (latest) - Microsoft Edge (latest)

Limited Support: - Safari (may have some issues with interactive features)

Not Supported: - Internet Explorer

Q: Some features don't work in my browser

  1. Update browser: Ensure you're using the latest version
  2. Enable JavaScript: Required for all interactive features
  3. Clear cache: Browser cache may cause issues
  4. Try different browser: Test in Chrome or Firefox

Performance

Q: How many data points can the app handle?

Guidelines: - \<1,000 points: Excellent performance on all pages - 1,000-10,000 points: Good performance, some pages may be slower - 10,000-100,000 points: Use sets and filtering, resampler helps - >100,000 points: Consider pre-filtering or using database queries

Q: The app is using too much memory

Solutions: 1. Close unused results: Delete data sources you're not using 2. Use sets: Work with subsets instead of full datasets 3. Restart app: Fresh start clears memory 4. Use database storage: More memory-efficient than in-memory

Errors and Debugging

Q: I see an error message. What should I do?

  1. Read the error: Error messages usually indicate the problem
  2. Check logs: Go to Logs page for detailed information
  3. Refresh page: Sometimes resolves temporary issues
  4. Restart app: Close and restart the application
  5. Check data: Verify your data format is correct

Q: How do I report a bug?

  1. Check logs: Note any error messages
  2. Document steps: Write down how to reproduce the issue
  3. Gather information: Browser version, data format, etc.
  4. Create issue: Report on the GitHub repository

Q: Where can I find detailed logs?

Navigate to the Logs page in the app (under Debug category) to view application logs.

Advanced Usage

Q: Can I add custom pages?

Yes! See the Adding Pages documentation for details on creating custom pages.

Q: Can I customize the theme?

The app supports light and dark themes. For more extensive customization, you'll need to modify the source code.

Q: Can I run the app on a server?

Yes, but you'll need to configure it for production use: - Set appropriate host and port - Configure security settings - Consider using a WSGI server - Implement authentication if needed

Q: Can I integrate the app with my workflow?

The app can be extended with custom pages and components. For deeper integration, consider using the OptiScope Python library directly.

Data Format Questions

Q: What format should my CSV file be in?

Your CSV should have: - Header row: Column names - Data rows: One row per solution - Columns: Variables, objectives, constraints, observables

Example: 

var1,var2,obj1,obj2,constraint1
1.0,2.0,5.0,3.0,-0.5
1.5,2.5,4.5,3.5,0.2

Q: How do I specify variable types?

The app automatically detects variable types based on column names or metadata. For custom types, you may need to use the Python library to create properly formatted data.

Q: Can I include metadata?

Yes, when using database formats or the Python library, you can include metadata about your optimization problem.

Still Having Issues?

If your question isn't answered here:

  1. Check the documentation: Review the Usage Guide and Page Reference
  2. Search GitHub issues: Someone may have had the same problem
  3. Ask for help: Create a GitHub issue with details
  4. Community: Check if there's a community forum or chat

Tips for Success

Best Practices

  1. Start simple: Load one result, explore, then add complexity
  2. Use sets early: Create default sets as soon as you load data
  3. Save frequently: Export important results regularly
  4. Document findings: Keep notes on your analysis
  5. Experiment: Try different visualizations and filters

Common Workflows

See the Pages Index for typical workflows and usage patterns.

Getting Help

  • Documentation: Start with the Usage Guide
  • Examples: Check the examples in the library documentation
  • GitHub: Report issues or request features
  • Code: The app is open source—you can inspect and modify it